SoQt(3)

📦
version 1.6.2 · 3 versions
, in opensuse-leap 16.0

💖 NAME 💖

okay bestie, this is the SoQt(3) manual page. The SoQt class takes care of Qt initialization and event dispatching. That’s the whole name-section vibe.

✨ SYNOPSIS ✨

#include <Inventor/Qt/SoQt.h>

🎀 Public Types 🎀

enum FatalErrors { UNSPECIFIED_ERROR = 0, NO_OPENGL_CANVAS,
    INTERNAL_ASSERT }
enum ABIType { DLL, LIB, UNKNOWN }
typedef void FatalErrorCB(const SbString errmsg, SoQt::FatalErrors
    errcode, void *userdata)

🌸 Static Public Member Functions 🌸

static QWidget * init (const char *appname, const char
    *classname='SoQt')
static QWidget * init (int &argc, char **argv, const char *appname,
    const char *classname='SoQt')
static void init (QWidget *toplevelwidget)
static void mainLoop (void)
static void exitMainLoop (void)
static void done (void)
static QWidget * getTopLevelWidget (void)
static QWidget * getShellWidget (const QWidget *w)
static void show (QWidget *const widget)
static void hide (QWidget *const widget)
static void setWidgetSize (QWidget *const widget, const SbVec2s size)
static SbVec2s getWidgetSize (const QWidget *widget)
static void createSimpleErrorDialog (QWidget *widget, const char *title,
    const char *string1, const char *string2=NULL)
static void getVersionInfo (int *major=NULL, int *minor=NULL, int
    *micro=NULL)
static const char * getVersionString (void)
static const char * getVersionToolkitString (void)
static FatalErrorCB * setFatalErrorHandler (SoQt::FatalErrorCB *cb, void
    *userdata)
static SbBool isDebugLibrary (void)
static SbBool isCompatible (unsigned int major, unsigned int minor)
static ABIType getABIType (void)
static void lockGL (void)
static void unlockGL (void)

that’s the whole function roster, bestie — every single one is static, and yes, all the defaults and types are exactly as shown 💅

🦋 Detailed Description 🦋

The SoQt class takes care of Qt initialization and event dispatching.

This is literally the “application-wide” class, and it’s solely static methods handling initialization and event processing tasks. You must use this class in any application built on top of the SoQt library. no cap.

Typical usage is as follows — and yes, this is complete application code:

#include <Inventor/Qt/SoQt.h>
#include <Inventor/Qt/viewers/SoQtExaminerViewer.h>
#include <Inventor/nodes/SoBaseColor.h>
#include <Inventor/nodes/SoCone.h>
#include <Inventor/nodes/SoSeparator.h>

int
main(int argc, char ** argv)
{
  // Initialize SoQt and Inventor API libraries. This returns a main
  // window to use.
  QWidget* mainwin = SoQt::init(argc, argv, argv[0]);

  // Make a dead simple scene graph, only containing a single
  // yellow cone under the scene graph root.
  SoSeparator * root = new SoSeparator;
  root->ref();

  SoBaseColor * col = new SoBaseColor;
  col->rgb = SbColor(1, 1, 0);
  root->addChild(col);

  root->addChild(new SoCone);

  // Use one of the convenient viewer classes.
  SoQtExaminerViewer * eviewer = new SoQtExaminerViewer(mainwin);
  eviewer->setSceneGraph(root);
  eviewer->show();

  // Pop up the main window.
  SoQt::show(mainwin);
  // Loop until exit.
  SoQt::mainLoop();

  // Clean up resources.
  delete eviewer;
  root->unref();
  SoQt::done();

  return 0;
}

And voila:

See also: SoQtComponent

💅 Member Typedef Documentation 💅

🫶 typedef void SoQt::FatalErrorCB(const SbString errmsg, SoQt::FatalErrors errcode, void *userdata)

An application function callback for handling fatal errors should be of this type. fatal is not a vibe, it’s the whole name.

The first argument is an error message in English describing the details of the error. The second argument is an error code used so the application can identify specific conditions. The third argument is the userdata pointer passed in to SoQt::setFatalErrorHandler().

🌈 Member Enumeration Documentation 🌈

🍓 enum SoQt::FatalErrors 🍓

Numerical identifiers for classifying the different kinds of possible fatal errors.

Enumerator

  • UNSPECIFIED_ERROR — Signifies that we were not able to specify in any greater detail the error condition that came up. it’s giving “something happened, and that’s all we know” 😭
  • NO_OPENGL_CANVAS — Could not construct any valid OpenGL canvas. Something is very wrong on the client system.
  • INTERNAL_ASSERT — An internal error condition that should never happen was detected. The most likely cause of this are programming errors within the SoQt library itself.

🧚 enum SoQt::ABIType 🧚

Numerical identifiers to identify how the library was built.

Enumerator

  • DLL — The SoQt library was built as a dynamic link library (aka “sharedlibrary”).
  • LIB — The SoQt library was built as a static library.
  • UNKNOWN — The SoQt introspection mechanisms cannot decide how the library was built.

💅 MEMBER FUNCTION DOCUMENTATION 💅

Okay bestie, this is the part where we go function by function. Grab a snack, it's giving long-but-worth-it. 🍓

🫶 SoQt::init — the legacy-ish one

QWidget * SoQt::init (const char * appname, const char * classname = 'SoQt') [static]

This one initializes the SoQt library and the Inventor API. The Inventor part happens by calling SoDB::init(), SoNodeKit::init() and SoInteraction::init(). All three. No skips. ✨

The QWidget* you get back is a top level shell widget for the application, and you can use it as a shell for your main component. That's literally its whole job.

Lowkey the point of this overload is easier porting / compatibility with the original SGI Inventor InventorXt library 🧚 — it just adds dummy argc and argv arguments and then calls the SoQt::init() method right below this one. Periodt.

💖 SoQt::init — the argc/argv main-character one

QWidget * SoQt::init (int & argc, char ** argv, const char * appname, const char * classname = 'SoQt') [static]

Same deal as above: initializes the SoQt library and the Inventor API, the latter by calling SoDB::init(), SoNodeKit::init() and SoInteraction::init(). 💫

The extra slay here: it creates an application framework and constructs and returns a main widget for you. So you don't have to. You're welcome.

And again — the returned QWidget* is a top level shell widget for the application, usable as a shell for the main component. 👑

🎀 SoQt::init — the "I already built my own stuff" one

void SoQt::init (QWidget * toplevelwidget) [static]

Yup, the library init again: SoQt plus the Inventor API, via SoDB::init(), SoNodeKit::init() and SoInteraction::init(). 🌸

This one assumes you're creating your own application framework and main widget — very DIY of you — and toplevelwidget should be your application's main widget. That's the whole vibe check.

🔥 SoQt::mainLoop

void SoQt::mainLoop (void) [static]

The event dispatch loop. The engine room. The main character energy of the whole thing. 💅

It does not return until application exit is somehow forced — either programmatically from the relevant API-call of the native toolkit, or when the user closes the application's main widget. It's just gonna sit there looping until somebody says stop, no cap.

After the main loop has finished execution (yes, after), call SoQt::done() to clean up static data. Don't forget, bestie. 🫶

🦋 SoQt::exitMainLoop

void SoQt::exitMainLoop (void) [static]

This one makes the main event loop finish looping. Bye loop, it was iconic. 👋

NOTE: exitMainLoop() is not present in the original API for SGI's InventorXt library.

⭐ SoQt::done

void SoQt::done (void) [static]

Cleans up all the static data the SoQt library allocated on initialization. Satisfying. 🧹

Heads up though — this function calls SoDB::finish(), which means no Coin classes should be used after it has been called. Like, none. We mean it. 💀

It should never be invoked more than once, and that one time is just before application exit, because it deallocates static data that was allocated as "one-off" operations in SoQt::init(). So: once, at the end. That's the rule. 🙈

NOTE: done() is not present in the original API for SGI's InventorXt library.

🌈 SoQt::getTopLevelWidget

QWidget * SoQt::getTopLevelWidget (void) [static]

Returns the QWidget* that is the main widget for the application. And when this widget gets closed, SoQt::mainLoop() will return — unless the close event is caught by the user, in which case, plot twist, it won't. 😭

See also: getShellWidget()

🌸 SoQt::getShellWidget

QWidget * SoQt::getShellWidget (const QWidget * w) [static]

Returns a pointer to the Qt QWidget that is the top level widget for the given QWidget w. 💫

Honestly this is just a convenience function so Open Inventor apps based on SoXt components are easier to port — because you can do the exact same thing by calling the QWidget::topLevelWidget() method directly on w. Convenience is convenience though. 🎀

See also: getTopLevelWidget()

👑 SoQt::show

void SoQt::show (QWidget *const widget) [static]

Provided for easier porting / compatibility with the Open Inventor SoXt component classes. It'll call QWidget::show() and QWidget::raise() on the widget pointer you hand it. So it shows and raises. Overachiever behavior, we love to see it. ✨

See also: hide()

💜 SoQt::hide

void SoQt::hide (QWidget *const widget) [static]

Also for easier porting / compatibility with the Open Inventor SoXt component classes. It calls QWidget::hide() on the provided widget pointer. Just the one call. Simple. Elegant. 🦋

See also: show()

🍓 SoQt::setWidgetSize

void SoQt::setWidgetSize (QWidget *const w, const SbVec2s size) [static]

Here for easier porting of apps based on the Open Inventor SoXt component classes. It calls QWidget::resize() on the w widget pointer you pass in. Resize and slay. 💅

See also: getWidgetSize()

🧚 SoQt::getWidgetSize

SbVec2s SoQt::getWidgetSize (const QWidget * w) [static]

Provided for easier porting / compatibility with the Open Inventor SoXt component classes. It does the same thing as calling QWidget::size() — except it returns an SbVec2s, which is the whole little twist of this function. 🌟

See also: setWidgetSize()

😭 SoQt::createSimpleErrorDialog

void SoQt::createSimpleErrorDialog (QWidget * widget, const char * title, const char * string1, const char * string2 = NULL) [static]

A convenient way for the application programmer to throw up an obtrusive, application-global error dialog. Yes, obtrusive is the word. It's supposed to be. 🔥

  • If widget is NULL, the dialog will be modal for the whole application — every single window gets blocked for input. All of them.
  • If widget isn't NULL, only the window for that given widget will be blocked. Much more chill.

title is the title of the dialog box. string1 and string2 contain the text that will be shown in the dialog box. 📝

There will only be a single "OK" button for the user to press and then continue with the application. One button. No choices. iykyk. 🫶

💀 SoQt::getVersionInfo

void SoQt::getVersionInfo (int * major = NULL, int * minor = NULL, int * micro = NULL) [static]

This method fills in the integers pointed to by the arguments with the corresponding part of the version release number of the SoQt library. So major gets the major, minor gets the minor, micro gets the micro. 🎯

A NULL pointer makes that part of the version number be ignored. Passing NULL is valid, it's just you saying "don't care." 🙈

This method is not part of the original InventorXt API from SGI.

🎀 SoQt::getVersionString

const char * SoQt::getVersionString (void) [static]

Returns a string containing the version id of the library. That's it, that's the function. ⭐

This method is not part of the original InventorXt API from SGI.

🌈 SoQt::getVersionToolkitString

const char * SoQt::getVersionToolkitString (void) [static]

Returns a string containing the version id of the Qt toolkit that the SoQt library is linked against. Slightly different fact than the one above, don't mix them up bestie. 🧚

This method is not part of the original InventorXt API from SGI.

🚨 SoQt::setFatalErrorHandler

SoQt::FatalErrorCB * SoQt::setFatalErrorHandler (SoQt::FatalErrorCB * cb, void * userdata) [static]

Sets up a callback to be invoked in the case of unexpected fatal error conditions within the SoQt library. Big responsibility, honestly. 💅

Almost any error condition inside the library is handled in a robust way through return values indicating errors for the offending calls — so the vast majority of the time you're fine. But there are a few cases that are impossible to handle without seriously crippling the functionality. 😭

(One example: if we fail to find any way of making a valid OpenGL canvas. That's an indication that something is seriously wrong on the end-user's system, and the SoQt library will not work properly.)

In the case of a fatal error, it is expected that the given application callback function communicates the problem to the end-user and then either exits the application or at least refrains from using any part of the SoQt library. Those are the options. 👑

If no callback is explicitly set up by the application, the SoQt library will display an error message to the end-user and then exit the application. So it handles it itself, dramatically. 💀

When setting a callback, this method returns a pointer to the previous callback function, or NULL if there was none. 🎁

(This is an extension versus the original SGI InventorXt library API.)

On a related note — be aware that the end-user will still be notified about non-fatal errors and warning messages through a dialog box. So this callback doesn't silence those. If you want to handle those yourself, or if you don't want your end-user seeing any of these non-critical messages, you'll also need to install an error handler callback function on the Coin library itself:
SoDebugError::setHandlerCallback(myErrorHandlerCB, myCBUserData);

(Please also see the documentation of SoDebugError::setHandlerCallback().) 🌸

🦋 SoQt::isDebugLibrary

SbBool SoQt::isDebugLibrary (void) [static]

Returns TRUE if this binary version of the SoQt library was compiled with debug settings on. Debug girlies rise. 🔍

This method was not part of the original SGI InventorXt library, but is an extension specific to the Coin project.

💖 SoQt::isCompatible

SbBool SoQt::isCompatible (unsigned int major, unsigned int minor) [static]

Returns TRUE if this version of the SoQt library has an Application Binary Interface compatible with the version you pass in as major and minor. Compatibility check, slay. ✅

This method was not part of the original SGI InventorXt library, but is an extension specific to the Coin project.

🌟 SoQt::getABIType

SoQt::ABIType SoQt::getABIType (void) [static]

Returns an indication on how the library was compiled: as a dynamic library, or as a static library. Two vibes, one return value. 🎀

This method was not part of the original SGI InventorXt library, but is an extension specific to the Coin project.

🔒 SoQt::lockGL

void SoQt::lockGL (void) [static]

Locks other threads out of a code section until the caller thread invokes SoQt::unlockGL(). Threads stay in their lane. 🚧

It's meant to protect several threads invoking OpenGL calls in parallel, in case the underlying OpenGL implementation isn't multi-thread safe. Safety first, bestie. 🛡️

For convenience, the function can be invoked through the SOQT_ENTER_GL_SECTION().

This method is not part of the original InventorXt API from SGI.

🔓 SoQt::unlockGL

void SoQt::unlockGL (void) [static]

See the documentation for SoQt::lockGL(). It's the other half of the pair — you lock, you do the thing, you unlock. 💫

For convenience, the function can be invoked through the SOQT_LEAVE_GL_SECTION().

This method is not part of the original InventorXt API from SGI.

👑 AUTHOR 👑

Generated automatically by Doxygen for SoQt from the source code. (The robots wrote this part, not me. 🤖💅)

That's the whole page, bestie — you made it to the end! 🎉 This was version 1.6.2, generated Sat Jan 6 2024 12:20:55. Go forth and initialize responsibly. 🫶✨

📦 where this page comes from