SOXT(3iv)

💖 SoXt 💖

okay bestie, so this is the manual page for SoXt from the SoXt(3IV) manual — it's the whole Inventor/Xt compatibility situation and honestly it's giving "glue code that holds the whole vibe together" 🫶

---

🎀 NAME 🎀

SoXt — routines for Inventor/Xt compatibility.

---

🦋 INHERITS FROM 🦋

SoXt

---

✨ SYNOPSIS ✨

#include <Inventor/Xt/SoXt.h>

Methods from class SoXt:

static Widget        init(const char *appName, const char *className =
                          "Inventor")
static void          init(Widget topLevelWidget)
static void          mainLoop()
static void          nextEvent(XtAppContext appContext, XEvent *event)
static Boolean       dispatchEvent(XEvent *event)
static XtAppContext  getAppContext()
static Display *     getDisplay()
static Widget        getTopLevelWidget()
static void          show(Widget widget)
static void          hide(Widget widget)
static XmString      encodeString(char *s)
static char *        decodeString(XmString xs)
static void          setWidgetSize(Widget w, const SbVec2s &size)
static SbVec2s       getWidgetSize(Widget w)
static Widget        getShellWidget(Widget w)
static void          createSimpleErrorDialog(Widget widget, char
                          *dialogTitle, char *errorStr1, char *errorStr2 =
                          NULL)
static void          getPopupArgs(Display *d, int scr, ArgList args, int
                          *n)
static void          registerColormapLoad(Widget widget, Widget shell)
static void          addColormapToShell(Widget widget, Widget shell)
static void          removeColormapFromShell(Widget widget, Widget shell)

---

💅 DESCRIPTION 💅

so like, the SoXt class initializes Inventor so it can hang out with the Xt toolkit and Motif. no cap, you have to call SoXt::init() or Inventor will simply not work properly with Xt — that's not a suggestion, that's the law fr fr 😭

and SoXt::mainLoop() also has to get called, because that's the whole reason extension device events actually make it to your Inventor render areas. the rest of the methods? convenience functions, lil helpers, the supporting cast ✨

if you want actual examples of how this class is supposed to be used with Inventor Xt components, go read the SoXtComponent man pages. that's the homework, bestie 📚

---

👑 METHODS 👑

• static Widget init(const char *appName, const char *className = "Inventor") — you call this to initialize Inventor and Xt, and to bind Inventor with Xt event handling so Inventor sensors actually work the way they're supposed to. it hands you back the top level shell widget. under the hood this method calls SoDB::init(), SoNodeKit::init(), SoInteraction::init() and XtAppInitialize(). slay.
• static void init(Widget topLevelWidget) — the alternate form, for when you want to be the one initializing Xt. the widget you pass in should be the top level shell widget that came back from the Xt initialization. and yep, this one also calls SoDB::init(), SoNodeKit::init(), SoInteraction::init() and XtAppInitialize().
• static void mainLoop() — this grabs events and dispatches them, and it loops forever. here's the tea: Xt straight up ignores extension devices (aka literally any device that isn't a mouse or keyboard) 🙈 — but this main loop will dispatch events from input extension devices like the spaceball. it pulls that off by calling SoXt::nextEvent() and SoXt::dispatchEvent(). if you're only using mouse and keyboard though, this is equivalent to calling XtAppMainLoop().
• static void nextEvent(XtAppContext appContext, XEvent *event) — gets the next event by calling XtAppNextEvent(). need the appContext? just call SoXt::getAppContext() and it's yours 💖
• static Boolean dispatchEvent(XEvent *event) — dispatches the event you pass in to a handler. mouse and keyboard events go out via XtDispatchEvent(). events from input extension devices get dispatched by code implemented right here in this routine. returns True if a handler was found, otherwise it returns False.
• static XtAppContext getAppContext()
• static Display * getDisplay()
• static Widget getTopLevelWidget()

these three return info based on the top level widget that was returned by init or passed to init. iconic trio, honestly.

• static void show(Widget widget)
• static void hide(Widget widget)

convenience routines to show and hide the widget you hand over.

for a shell widget, this is equivalent to calling RealizeWidget() + XMapWindow(), or XMapRaised() if the window already exists (which raises it and de-iconifies it). then hide() calls XUnmapWindow().

for a subwidget, those simply call XtManageChild() and XtUnmanageChild().

• static XmString encodeString(char *s)
• static char * decodeString(XmString xs)

convenience routines for encoding a character string as an XmString, and decoding an XmString back into a character string. (XmString is a Motif string, iykyk.) ⚠️ heads up: you are responsible for freeing the memory those return values point at. use XmStringFree() to free an XmString, and free() to free a character pointer.

• static void setWidgetSize(Widget w, const SbVec2s &size)
• static SbVec2s getWidgetSize(Widget w)

convenience routines to set/get the size of the given widget. these are equivalent to calling XtSetValues() and XtGetValues() on the XtNheight and XtNwidth widget resources.

• static Widget getShellWidget(Widget w)

convenience routine that returns the ShellWidget containing the widget you passed in. it walks the widget tree upward until it finds a shell widget, using XtIsShell().

• static void createSimpleErrorDialog(Widget widget, char *dialogTitle, char *errorStr1, char *errorStr2 = NULL)

convenience routine that brings up a simple motif error dialog box showing the error string(s) and window title you gave it. the only button on it is the OK button, which destroys the dialog. the widget argument is used to create and center the dialog (using XmCreateErrorDialog()).

• static void getPopupArgs(Display *d, int scr, ArgList args, int *n)

convenience routine that gets visual args for the popup planes. you can then pass those args into XmCreatePulldownMenu() or XmCreatePopupMenu() to create menus in the popup planes. 💀 important: registerColormapLoad() must be called for each pulldown menu, so the overlay color map loads/unloads on the shell properly when it's needed.

• static void registerColormapLoad(Widget widget, Widget shell)

convenience routine that registers map/unmap callbacks to load and unload the pulldown menu color map right before the menu is about to be posted. call this when you're creating pulldown or popup menus in the overlays. it makes sure the right color map gets loaded into the shell widget (so the pulldown/popup actually looks right) and removes it when it's no longer needed (so the OpenGL overlay widget color map is correctly loaded on 8 bit machines). the way that it handles both of those? obsessed. ✨

• static void addColormapToShell(Widget widget, Widget shell)
• static void removeColormapFromShell(Widget widget, Widget shell)

convenience routine to insert/remove the given widget colormap onto the supplied shell widget. and nope, it does not replace the existing installed colormaps (or the list of windows) — instead it inserts the new colormap first into the existing list, using XGetWMColormapWindows() and XSetWMColormapWindows().

---

🌈 SEE ALSO 🌈

SoXtComponent

---

and that's the whole page, bestie 🫶 this was the SoXt(3IV) manual page — so consider this your cute lil sign-off from the SoXt(3IV) source/version, no date needed, we're timeless 💜✨