Man Linux: Main Page and Category List

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 <Inventor/Qt/SoQt.h>

   Public Types
       enum FatalErrors { UNSPECIFIED_ERROR =  0, NO_OPENGL_CANVAS,
           INTERNAL_ASSERT }
       enum ABIType { DLL, LIB, UNKNOWN }

   Public Member Functions
       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 <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 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();

           return 0;
         }

       And voila:

       See also:
           SoQtComponent

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.

       References init().

   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.

       An important note: be careful about how you handle SoQtComponent-
       derived objects after the application control returns from mainLoop(),
       as SoQt will then have been ’cleaned up’ with regards to various
       internal resources. So doing for instance something like this:

         SoQt::mainLoop();
         viewer->hide();

       Deleting a component after mainLoop() returns is allowed, though, and
       also necessary to avoid getting reports of possible memory leaks from
       memleak checkers.

       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.

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

   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.

   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.

   void SoQt::FatalErrorCB (const SbString errmsg, SoQt::FatalErrors errcode,
       void * userdata)
       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().

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