xpaconvert(n)

👑 xpaconvert(n) — the glow-up guide

okay bestie, so this is XPAConvert and it lives in the SAORD Documentation manual, section n. it's literally the "how do i take my crusty xpa 1.0 code and make it serve 2.0" doc. we love a transformation arc ✨

---

🦋 SYNOPSIS

This document describes tips for converting from xpa 1.0 (Xt-based xpa) to xpa 2.0 (socket-based xpa).

no cap, that's the whole vibe. it's a tips doc, not a program. she's giving ✨migration era✨

---

💖 DESCRIPTION

okay so here's the tea: 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). slay, macros. automation ate. 💅

• 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).

this is your little detector, your vibe check, your "which era am i in" radar. if XPA_VERSION exists → you're in 2.0. if it doesn't → 1.0. iconic.

• Remove the first widget argument from all send and receive server callbacks. Also change first 2 arguments from XtPointer to void *. For example:

#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

see how the 2.0 branch just… dropped the widget? no w, no Widget, no XtPointer. she said "not me carrying around a whole Xt widget for no reason" and she was RIGHT. 💀

• Server callbacks should be declared as returning int instead of void. They now should return 0 for no errors, -1 for error.

bestie listen. 0 = good, -1 = bad. that's it. that's the whole personality. don't return vibes, return numbers. 🙈

• The mode flags have changed when defining XPA server callbacks. The old S flag (save buffer) is replaced by freebuf=false. The old E flag (empty buffer is OK) is no longer used (it was an artifact of the X implementation).

so if you're out here still typing "SE" like it's 1999… ma'am. S is now freebuf=false, and E is just GONE. gone gone. it was an X-implementation artifact, it never had main character energy anyway. ✨

• Change NewXPACommand() to XPAcmdNew(), with the new calling sequence:

xpa = NewXPACommand(toplevel, NULL, prefix, NULL);

is changed to:

xpa = XPACmdNew(xclass, name);

four args → two args. she dropped the toplevel, she dropped the NULLs, she said "i'm lowkey minimal now." 🔥

• Change the AddXPACommand() subroutine name to XPACmdAdd (with the same calling sequence):

AddXPACommand(xpa, "file",
  "\tdisplay a new file\n\t\t  requires: filename",
  NULL, NULL, NULL, XPAReceiveFile, text, NULL);

is changed to:

XPACmdAdd(xpa, "file",
  "\tdisplay a new file\n\t\t  requires: filename",
  NULL, NULL, NULL, XPAReceiveFile, text, NULL);

same calling sequence, just a lil rebrand. the way that AddXPACommand became XPACmdAdd and changed literally nothing else?? we love a low-effort glow-up. 💅

• The XPAXtAppInput() routine should be called just before XtAppMainLoop() to add xpa fds to the Xt event loop:

/* add the xpas to the Xt loop */
XPAXtAddInput(app, NULL);

/* process events */
XtAppMainLoop(app);

plug the xpa fds into the Xt event loop FIRST, then let XtAppMainLoop(app) do her thing. order matters, bestie. don't skip the hookup. 🫶

• Change NewXPA() to XPANew() and call XPAXtAddInput() if the XtAppMainLoop routine already has been entered:

xpa = NewXPA(saotng->xim->toplevel, prefix, xparoot,
             "FITS data or image filename\n\t\t  options: file type",
             XPASendData, new, NULL,
             XPAReceiveData, new, "SE");

is changed to:

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);

look at her go. the toplevel arg got swapped for a literal class name "SAOTNG", the prefix/xparoot got sprintf-ed into tbuf with a "%s.%s" glue, and if XtAppMainLoop is already running you gotta manually XPAXtAddInput(XtWidgetToApplicationContext(saotng->xim->toplevel), xpa). main character energy fr fr. 👑

• Change XPAInternalReceiveCommand() to XPACmdInternalReceive() remove first argument in the calling sequence):

XPAInternalReceiveCommand(im->saotng->xim->toplevel,
                          im->saotng, im->saotng->commands,
                          "zoom reset", NULL, 0);

is changed to:

XPACmdInternalReceive(im->saotng, im->saotng->commands,
                      "zoom reset", NULL, 0);

the first arg — that whole toplevel — got evicted. bye girl. ✨

• Change DestroyXPA to XPAFree:

DestroyXPA(im->dataxpa);

is changed to:

XPAFree(im->dataxpa);

she's not "destroying" anymore, she's "freeing." same energy, cleaner branding. it's giving ✨self-care✨. 🌸

---

🌈 SEE ALSO

See xpa(n) for a list of XPA help pages

go read xpa(n) bestie, it's the whole index of help pages and it's a whole mood 💖

---

that's the doc, babe. this one's version 2.1.15, dated July 23, 2013, from the SAORD Documentation crew — mwah, thank you for your service, converting Xt-era code was NOT for the weak. 🎀✨