.TH "SoQt" 3 "Fri Dec 29 2017" "Version 1.6.0a" "SoQt" \" -*- nroff -*- .ad l .nh .SH NAME SoQt \- The \fBSoQt\fP class takes care of Qt initialization and event dispatching\&. .PP 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 \fBSoQt\fP library\&. .SH SYNOPSIS .br .PP .PP \fC#include \fP .SS "Public Types" .in +1c .ti -1c .RI "enum \fBFatalErrors\fP { \fBUNSPECIFIED_ERROR\fP = 0, \fBNO_OPENGL_CANVAS\fP, \fBINTERNAL_ASSERT\fP }" .br .ti -1c .RI "enum \fBABIType\fP { \fBDLL\fP, \fBLIB\fP, \fBUNKNOWN\fP }" .br .ti -1c .RI "typedef void \fBFatalErrorCB\fP(const SbString errmsg, \fBSoQt::FatalErrors\fP errcode, void *userdata)" .br .in -1c .SS "Static Public Member Functions" .in +1c .ti -1c .RI "static QWidget * \fBinit\fP (const char *appname, const char *classname='SoQt')" .br .ti -1c .RI "static QWidget * \fBinit\fP (int &argc, char **argv, const char *appname, const char *classname='SoQt')" .br .ti -1c .RI "static void \fBinit\fP (QWidget *toplevelwidget)" .br .ti -1c .RI "static void \fBmainLoop\fP (void)" .br .ti -1c .RI "static void \fBexitMainLoop\fP (void)" .br .ti -1c .RI "static void \fBdone\fP (void)" .br .ti -1c .RI "static QWidget * \fBgetTopLevelWidget\fP (void)" .br .ti -1c .RI "static QWidget * \fBgetShellWidget\fP (const QWidget *w)" .br .ti -1c .RI "static void \fBshow\fP (QWidget *const widget)" .br .ti -1c .RI "static void \fBhide\fP (QWidget *const widget)" .br .ti -1c .RI "static void \fBsetWidgetSize\fP (QWidget *const widget, const SbVec2s size)" .br .ti -1c .RI "static SbVec2s \fBgetWidgetSize\fP (const QWidget *widget)" .br .ti -1c .RI "static void \fBcreateSimpleErrorDialog\fP (QWidget *widget, const char *title, const char *string1, const char *string2=NULL)" .br .ti -1c .RI "static void \fBgetVersionInfo\fP (int *major=NULL, int *minor=NULL, int *micro=NULL)" .br .ti -1c .RI "static const char * \fBgetVersionString\fP (void)" .br .ti -1c .RI "static const char * \fBgetVersionToolkitString\fP (void)" .br .ti -1c .RI "static \fBFatalErrorCB\fP * \fBsetFatalErrorHandler\fP (\fBSoQt::FatalErrorCB\fP *cb, void *userdata)" .br .ti -1c .RI "static SbBool \fBisDebugLibrary\fP (void)" .br .ti -1c .RI "static SbBool \fBisCompatible\fP (unsigned int major, unsigned int minor)" .br .ti -1c .RI "static \fBABIType\fP \fBgetABIType\fP (void)" .br .ti -1c .RI "static void \fBlockGL\fP (void)" .br .ti -1c .RI "static void \fBunlockGL\fP (void)" .br .in -1c .SS "Friends" .in +1c .ti -1c .RI "class \fBSoGuiP\fP" .br .ti -1c .RI "class \fBSoQtP\fP" .br .in -1c .SH "Detailed Description" .PP The \fBSoQt\fP class takes care of Qt initialization and event dispatching\&. .PP 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 \fBSoQt\fP library\&. Typical usage is as follows (complete application code): .PP .PP .nf #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; } .fi .PP .PP And voila: .PP .PP \fBSee also:\fP .RS 4 \fBSoQtComponent\fP .RE .PP .SH "Member Typedef Documentation" .PP .SS "void SoQt::FatalErrorCB" An application function callback for handling fatal errors should be of this type\&. .PP 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 \fBSoQt::setFatalErrorHandler()\fP\&. .SH "Member Enumeration Documentation" .PP .SS "enum \fBSoQt::FatalErrors\fP" Numerical identifiers for classifying the different kinds of possible fatal errors\&. .PP \fBEnumerator\fP .in +1c .TP \fB\fIUNSPECIFIED_ERROR \fP\fP Signifies that we were not able to specify in any greater detail the error condition that came up\&. .TP \fB\fINO_OPENGL_CANVAS \fP\fP Could not construct \fIany\fP valid OpenGL canvas\&. Something is very wrong on the client system\&. .TP \fB\fIINTERNAL_ASSERT \fP\fP An internal error condition that should never happen was detected\&. The most likely cause of this is programmering errors within the \fBSoQt\fP library itself\&. .SS "enum \fBSoQt::ABIType\fP" Numerical identifiers to identify how the library was built\&. .PP \fBEnumerator\fP .in +1c .TP \fB\fIDLL \fP\fP The \fBSoQt\fP library was built as a dynamic link library (aka 'shared library')\&. .TP \fB\fILIB \fP\fP The \fBSoQt\fP library was built as a static library\&. .TP \fB\fIUNKNOWN \fP\fP The \fBSoQt\fP introspection mechanisms can not decide how the library was built\&. .SH "Member Function Documentation" .PP .SS "QWidget * SoQt::init (const char * appname, const char * classname = \fC'SoQt'\fP)\fC [static]\fP" This function initializes the \fBSoQt\fP library, as well as the Inventor API\&. The latter is done by calling \fISoDB::init()\fP, \fISoNodeKit::init()\fP and \fISoInteraction::init()\fP\&. .PP The returned QWidget * is a toplevel shell widget for the application, which can be used as a shell for the main component\&. .PP This method is provided for easier porting / compatibility with the original SGI Inventor InventorXt library\&. It just adds dummy \fIargc\fP and \fIargv\fP arguments and calls the \fBSoQt::init()\fP method below\&. .PP Referenced by init()\&. .SS "QWidget * SoQt::init (int & argc, char ** argv, const char * appname, const char * classname = \fC'SoQt'\fP)\fC [static]\fP" This function initializes the \fBSoQt\fP library, as well as the Inventor API\&. The latter is done by calling \fISoDB::init()\fP, \fISoNodeKit::init()\fP and \fISoInteraction::init()\fP\&. .PP Creates an application framework and constructs and returns a main widget for you\&. .PP The returned QWidget * is a toplevel shell widget for the application, which can be used as a shell for the main component\&. .PP References init()\&. .SS "void SoQt::init (QWidget * toplevelwidget)\fC [static]\fP" This function initializes the \fBSoQt\fP library, as well as the Inventor API\&. The latter is done by calling \fISoDB::init()\fP, \fISoNodeKit::init()\fP and \fISoInteraction::init()\fP\&. .PP Assumes you are creating your own application framework and main widget\&. \fItoplevelwidget\fP should be your application's main widget\&. .SS "void SoQt::mainLoop (void)\fC [static]\fP" This is the event dispatch loop\&. .PP 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\&. .PP After the main loop has finished execution, call \fBSoQt::done()\fP to clean up static data\&. .PP References done()\&. .SS "void SoQt::exitMainLoop (void)\fC [static]\fP" This function will make the main event loop finish looping\&. .PP NOTE: \fBexitMainLoop()\fP is not present in the original API for SGI's InventorXt library\&. .SS "void SoQt::done (void)\fC [static]\fP" Cleans up all static data allocated by the \fBSoQt\fP library on initialization\&. .PP This functions calls SoDB::finish() which means that no Coin classes should be used after it has been called\&. .PP It should never be invoked more than \fIonce\fP, and that is just before application exit, as it deallocates \fIstatic\fP data allocated as 'one-off' operations in \fBSoQt::init()\fP\&. .PP NOTE: \fBdone()\fP is not present in the original API for SGI's InventorXt library\&. .PP Referenced by mainLoop()\&. .SS "QWidget * SoQt::getTopLevelWidget (void)\fC [static]\fP" Returns the QWidget * which is the main widget for the application\&. When this widget gets closed, \fBSoQt::mainLoop()\fP will return (unless the close event is caught by the user)\&. .PP \fBSee also:\fP .RS 4 \fBgetShellWidget()\fP .RE .PP .SS "QWidget * SoQt::getShellWidget (const QWidget * w)\fC [static]\fP" Returns a pointer to the Qt QWidget which is the top level widget for the given QWidget \fIw\fP\&. 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 \fIw\fP\&. .PP \fBSee also:\fP .RS 4 \fBgetTopLevelWidget()\fP .RE .PP .PP Referenced by SoQtComponent::getIconTitle(), SoQtComponent::getShellWidget(), SoQtComponent::setBaseWidget(), SoQtComponent::setFullScreen(), SoQtComponent::setIconTitle(), and SoQtComponent::setSize()\&. .SS "void SoQt::show (QWidget *const widget)\fC [static]\fP" 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 \fIwidget\fP pointer\&. .PP \fBSee also:\fP .RS 4 \fBhide()\fP .RE .PP .SS "void SoQt::hide (QWidget *const widget)\fC [static]\fP" This method is provided for easier porting/compatibility with the Open Inventor SoXt component classes\&. It will call QWidget::hide() on the provided \fIwidget\fP pointer\&. .PP \fBSee also:\fP .RS 4 \fBshow()\fP .RE .PP .SS "void SoQt::setWidgetSize (QWidget *const w, const SbVec2s size)\fC [static]\fP" 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 \fIw\fP widget pointer\&. .PP \fBSee also:\fP .RS 4 \fBgetWidgetSize()\fP .RE .PP .SS "SbVec2s SoQt::getWidgetSize (const QWidget * w)\fC [static]\fP" 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)\&. .PP \fBSee also:\fP .RS 4 \fBsetWidgetSize()\fP .RE .PP .SS "void SoQt::createSimpleErrorDialog (QWidget * widget, const char * title, const char * string1, const char * string2 = \fCNULL\fP)\fC [static]\fP" This is a convenient way for the application programmer to throw up an obtrusive application-global error dialog\&. .PP If \fIwidget\fP is \fCNULL\fP, the dialog will be modal for the whole application (all windows will be blocked for input)\&. If not, only the window for the given \fIwidget\fP will be blocked\&. .PP \fItitle\fP is the title of the dialog box\&. \fIstring1\fP and \fIstring2\fP contains the text which will be shown in the dialog box\&. .PP There will only be a single 'Ok' button for the user to press and continue with the application\&. .PP Referenced by getABIType()\&. .SS "void SoQt::getVersionInfo (int * major = \fCNULL\fP, int * minor = \fCNULL\fP, int * micro = \fCNULL\fP)\fC [static]\fP" This method will fill in the integers pointed to by the arguments with the corresponding part of the version release number of the \fBSoQt\fP library\&. .PP A \fCNULL\fP pointer will make that part of the version number be ignored\&. .PP This method is not part of the original InventorXt API from SGI\&. .SS "const char * SoQt::getVersionString (void)\fC [static]\fP" This method returns a string containing the version id of the library\&. .PP This method is not part of the original InventorXt API from SGI\&. .SS "const char * SoQt::getVersionToolkitString (void)\fC [static]\fP" This method returns a string containing the version id of the Qt toolkit the \fBSoQt\fP library is linked against\&. .PP This method is not part of the original InventorXt API from SGI\&. .SS "\fBSoQt::FatalErrorCB\fP * SoQt::setFatalErrorHandler (\fBSoQt::FatalErrorCB\fP * cb, void * userdata)\fC [static]\fP" Set up a callback to invoke in the case of unexpected fatal error conditions within the \fBSoQt\fP library\&. .PP 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\&. .PP (One example is if we fail to find \fIany\fP way of making a valid OpenGL canvas\&. This is an indication that something is seriously wrong on the end-user's system, and the \fBSoQt\fP library will not work properly\&.) .PP 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 \fBSoQt\fP library\&. .PP If no callback is explicitly set up by the application, the \fBSoQt\fP library will display an error message to the end-user and then exit the application\&. .PP When setting a callback, this method returns a pointer to the previous callback function, or \fCNULL\fP if none\&. .PP (This is an extension versus the original SGI InventorXt library API\&.) .PP 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: .PP .PP .nf SoDebugError::setHandlerCallback(myErrorHandlerCB, myCBUserData); .fi .PP .PP (Please also see the documentation of SoDebugError::setHandlerCallback()\&.) .SS "SbBool SoQt::isDebugLibrary (void)\fC [static]\fP" Returns \fCTRUE\fP if this binary version of the \fBSoQt\fP library was compiled with debug settings on\&. .PP This method was not part of the original SGI InventorXt library, but is an extension specific to the Coin project\&. .SS "SbBool SoQt::isCompatible (unsigned int major, unsigned int minor)\fC [static]\fP" Returns \fCTRUE\fP if this version of the \fBSoQt\fP library has an Application Binary Interface compatible with the given version\&. .PP This method was not part of the original SGI InventorXt library, but is an extension specific to the Coin project\&. .SS "\fBSoQt::ABIType\fP SoQt::getABIType (void)\fC [static]\fP" Returns an indication on how the library was compiled: as a dynamic library, or as a static library\&. .PP This method was not part of the original SGI InventorXt library, but is an extension specific to the Coin project\&. .PP References createSimpleErrorDialog(), DLL, LIB, and UNKNOWN\&. .SS "void SoQt::lockGL (void)\fC [static]\fP" This method locks other threads out from a code section until the caller thread invokes \fBSoQt::unlockGL()\fP\&. .PP It is meant to protect several threads invoking OpenGL calls in parallell, in case the underlying OpenGL implementation is not multi-thread safe\&. .PP For convenience, the function can be invoked through the SOQT_ENTER_GL_SECTION()\&. .PP This method is not part of the original InventorXt API from SGI\&. .SS "void SoQt::unlockGL (void)\fC [static]\fP" See documentation for \fBSoQt::lockGL()\fP\&. .PP For convenience, the function can be invoked through the SOQT_LEAVE_GL_SECTION()\&. .PP This method is not part of the original InventorXt API from SGI\&. .SH "Author" .PP Generated automatically by Doxygen for SoQt from the source code\&.