--- name: "SoQt" section: "3" platform: "linux" package: "libsoqt-dev-common" version: "1.6.0~e8310f-3" release: "Debian 9 (Stretch)" platforms: ["linux"] url: "https://new.carta.tech/SoQt" --- # SoQt(3) The SoQt class takes care of Qt initialization and event dispatching. This is the 'application-wide' class with solely static methods handling initialization and event processing tasks. You must use this class in any application built on top of the SoQt library. ## NAME SoQt - The **SoQt** class takes care of Qt initialization and event dispatching. This is the 'application-wide' class with solely static methods handling initialization and event processing tasks. You must use this class in any application built on top of the **SoQt** library. ## SYNOPSIS `#include ` ### 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)\ ### Friends class **SoGuiP**\ class **SoQtP**\ ## Detailed Description The **SoQt** class takes care of Qt initialization and event dispatching. This is the 'application-wide' class with solely static methods handling initialization and event processing tasks. You must use this class in any application built on top of the **SoQt** library. Typical usage is as follows (complete application code): ``` #include #include #include #include #include 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 scenegraph 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 ### void SoQt::FatalErrorCB An application function callback for handling fatal errors should be of this type. 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.* - *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 is programmering 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 'shared* *library').* - *LIB* *The* **SoQt** *library was built as a static library.* - *UNKNOWN* *The* **SoQt** *introspection mechanisms can not decide how the library was built.* ## Member Function Documentation ### QWidget \* SoQt::init (const char \* appname, const char \* classname = `'SoQt'`)` [static]` *This function initializes the* **SoQt** *library, as well as the Inventor API. The latter is done by calling SoDB::init(), SoNodeKit::init() and SoInteraction::init().* *The returned QWidget \* is a toplevel shell widget for the application, which can be used as a shell for the main component.* *This method is provided for easier porting / compatibility with the original SGI Inventor InventorXt library. It just adds dummy argc and argv arguments and calls the* **SoQt::init()** *method below.* *Referenced by init().* ### QWidget \* SoQt::init (int & argc, char \*\* argv, const char \* appname, const char \* classname = `'SoQt'`)` [static]` *This function initializes the* **SoQt** *library, as well as the Inventor API. The latter is done by calling SoDB::init(), SoNodeKit::init() and SoInteraction::init().* *Creates an application framework and constructs and returns a main widget for you.* *The returned QWidget \* is a toplevel shell widget for the application, which can be used as a shell for the main component.* *References init().* ### void SoQt::init (QWidget \* toplevelwidget)` [static]` *This function initializes the* **SoQt** *library, as well as the Inventor API. The latter is done by calling SoDB::init(), SoNodeKit::init() and SoInteraction::init().* *Assumes you are creating your own application framework and main widget. toplevelwidget should be your application's main widget.* ### void SoQt::mainLoop (void)` [static]` *This is the event dispatch loop.* *It doesn't 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.* *After the main loop has finished execution, call* **SoQt::done()** *to clean up static data.* *References done().* ### void SoQt::exitMainLoop (void)` [static]` *This function will make the main event loop finish looping.* *NOTE:* **exitMainLoop()** *is not present in the original API for SGI's InventorXt library.* ### void SoQt::done (void)` [static]` *Cleans up all static data allocated by the* **SoQt** *library on initialization.* *This functions calls SoDB::finish() which means that no Coin classes should be used after it has been called.* *It should never be invoked more than once, and that is just before application exit, as it deallocates static data allocated as 'one-off' operations in* **SoQt::init()***.* *NOTE:* **done()** *is not present in the original API for SGI's InventorXt library.* *Referenced by mainLoop().* ### QWidget \* SoQt::getTopLevelWidget (void)` [static]` *Returns the QWidget \* which is the main widget for the application. When this widget gets closed,* **SoQt::mainLoop()** *will return (unless the close event is caught by the user).* **See also:** **getShellWidget()** ### QWidget \* SoQt::getShellWidget (const QWidget \* w)` [static]` *Returns a pointer to the Qt QWidget which is the top level widget for the given QWidget w. This is just a convenience function provided for easier porting of Open Inventor applications based on SoXt components, as you can do the same thing by calling the QWidget::topLevelWidget() method directly on w.* **See also:** **getTopLevelWidget()** *Referenced by SoQtComponent::getIconTitle(), SoQtComponent::getShellWidget(), SoQtComponent::setBaseWidget(), SoQtComponent::setFullScreen(), SoQtComponent::setIconTitle(), and SoQtComponent::setSize().* ### void SoQt::show (QWidget \*const widget)` [static]` *This method is provided for easier porting/compatibility with the Open Inventor SoXt component classes. It will call QWidget::show() and QWidget::raise() on the provided widget pointer.* **See also:** **hide()** ### void SoQt::hide (QWidget \*const widget)` [static]` *This method is provided for easier porting/compatibility with the Open Inventor SoXt component classes. It will call QWidget::hide() on the provided widget pointer.* **See also:** **show()** ### void SoQt::setWidgetSize (QWidget \*const w, const SbVec2s size)` [static]` *This method is provided for easier porting of applications based on the Open Inventor SoXt component classes. It will call QWidget::resize() on the provided w widget pointer.* **See also:** **getWidgetSize()** ### SbVec2s SoQt::getWidgetSize (const QWidget \* w)` [static]` *This method is provided for easier porting/compatibility with the Open Inventor SoXt component classes. It will do the same as calling QWidget::size() (except that we're returning an SbVec2s).* **See also:** **setWidgetSize()** ### void SoQt::createSimpleErrorDialog (QWidget \* widget, const char \* title, const char \* string1, const char \* string2 = `NULL`)` [static]` *This is a convenient way for the application programmer to throw up an obtrusive application-global error dialog.* *If widget is* `NULL`*, the dialog will be modal for the whole application (all windows will be blocked for input). If not, only the window for the given widget will be blocked.* *title is the title of the dialog box. string1 and string2 contains the text which will be shown in the dialog box.* *There will only be a single 'Ok' button for the user to press and continue with the application.* *Referenced by getABIType().* ### void SoQt::getVersionInfo (int \* major = `NULL`, int \* minor = `NULL`, int \* micro = `NULL`)` [static]` *This method will fill in the integers pointed to by the arguments with the corresponding part of the version release number of the* **SoQt** *library.* *A* `NULL` *pointer will make that part of the version number be ignored.* *This method is not part of the original InventorXt API from SGI.* ### const char \* SoQt::getVersionString (void)` [static]` *This method returns a string containing the version id of the library.* *This method is not part of the original InventorXt API from SGI.* ### const char \* SoQt::getVersionToolkitString (void)` [static]` *This method returns a string containing the version id of the Qt toolkit the* **SoQt** *library is linked against.* *This method is not part of the original InventorXt API from SGI.* ### SoQt::FatalErrorCB \* SoQt::setFatalErrorHandler (SoQt::FatalErrorCB \* cb, void \* userdata)` [static]` *Set up a callback to invoke in the case of unexpected fatal error conditions within the* **SoQt** *library.* *Almost any error condition within the library is handled in a robust way through return values indicating errors for the offending calls, but there are a few cases that are impossible to handle without seriously crippling the functionality.* *(One example is if we fail to find any way of making a valid OpenGL canvas. This is 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.* *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.* *When setting a callback, this method returns a pointer to the previous callback function, or* `NULL` *if 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. If you want to handle these yourself, or if you don't want your end-user to see any of these non-critical messages, you will 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().)* ### SbBool SoQt::isDebugLibrary (void)` [static]` *Returns* `TRUE` *if this binary version of the* **SoQt** *library was compiled with debug settings on.* *This method was not part of the original SGI InventorXt library, but is an extension specific to the Coin project.* ### 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 given version.* *This method was not part of the original SGI InventorXt library, but is an extension specific to the Coin project.* ### SoQt::ABIType SoQt::getABIType (void)` [static]` *Returns an indication on how the library was compiled: as a dynamic library, or as a static library.* *This method was not part of the original SGI InventorXt library, but is an extension specific to the Coin project.* *References createSimpleErrorDialog(), DLL, LIB, and UNKNOWN.* ### void SoQt::lockGL (void)` [static]` *This method locks other threads out from a code section until the caller thread invokes* **SoQt::unlockGL()***.* *It is meant to protect several threads invoking OpenGL calls in parallell, in case the underlying OpenGL implementation is not multi-thread safe.* *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.* ### void SoQt::unlockGL (void)` [static]` *See documentation for* **SoQt::lockGL()***.* *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.*