SoWin  1.6.2
Coin3D GUI toolkit binding
Loading...
Searching...
No Matches
SoWin Class Reference

The SoWin class takes care of Win initialization and event dispatching. More...

#include <Inventor/Win/SoWin.h>

Public Types

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

Static Public Member Functions

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

Detailed Description

The SoWin class takes care of Win 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 SoWin library.

Typical usage is as follows (complete application code):

#include <Inventor/Win/SoWin.h>
#include <Inventor/Win/viewers/SoWinExaminerViewer.h>
#include <Inventor/nodes/SoBaseColor.h>
#include <Inventor/nodes/SoCone.h>
#include <Inventor/nodes/SoSeparator.h>
int
main(int argc, char ** argv)
{
// Initialize SoWin and Inventor API libraries. This returns a main
// window to use.
HWND mainwin = SoWin::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.
SoWinExaminerViewer * eviewer = new SoWinExaminerViewer(mainwin);
eviewer->setSceneGraph(root);
eviewer->show();
// Pop up the main window.
SoWin::show(mainwin);
// Loop until exit.
// Clean up resources.
delete eviewer;
root->unref();
return 0;
}
virtual void show(void)
Definition SoWinComponent.cpp:368
The SoWinExaminerViewer class is a 3D-model examination viewer.
Definition SoWinExaminerViewer.h:50
virtual void setSceneGraph(SoNode *root)
Definition SoWinViewer.cpp:2841
static void done(void)
Definition SoWin.cpp:417
static HWND init(const char *appname, const char *classname="SoWin")
Definition SoWinCommon.cpp:173
static void show(HWND const widget)
Definition SoWin.cpp:456
static void mainLoop(void)
Definition SoWin.cpp:375

And voila:

See also
SoWinComponent

Member Typedef Documentation

◆ FatalErrorCB

void SoWin::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 SoWin::setFatalErrorHandler().

Member Enumeration Documentation

◆ ABIType

Numerical identifiers to identify how the library was built.

Enumerator
DLL 

The SoWin library was built as a dynamic link library (aka "shared library").

LIB 

The SoWin library was built as a static library.

UNKNOWN 

The SoWin introspection mechanisms cannot decide how the library was built.

◆ 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 are programming errors within the SoWin library itself.

Member Function Documentation

◆ createSimpleErrorDialog()

void SoWin::createSimpleErrorDialog ( HWND 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.

◆ doIdleTasks()

void SoWin::doIdleTasks ( void )
static

Process all Inventor sensors scheduled for execution when the system is idle.

◆ done()

void SoWin::done ( void )
static

Cleans up all static data allocated by the SoWin 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 SoWin::init().

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

◆ exitMainLoop()

void SoWin::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.

◆ getABIType()

SoWin::ABIType SoWin::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.

◆ getShellWidget()

HWND SoWin::getShellWidget ( const HWND w)
static

Returns a pointer to the HWND which is the top level widget for the given HWND hwnd.

See also
getTopLevelWidget()

◆ getTopLevelWidget()

HWND SoWin::getTopLevelWidget ( void )
static

Returns the HWND which is the main widget for the application. When this widget gets closed, SoWin::mainLoop() will return (unless the close event is caught by the user).

See also
getShellWidget()

◆ getVersionInfo()

void SoWin::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 SoWin 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.

◆ getVersionString()

const char * SoWin::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.

◆ getVersionToolkitString()

const char * SoWin::getVersionToolkitString ( void )
static

This method returns a string containing the version id of the Win toolkit the SoWin library is linked against.

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

◆ getWidgetSize()

SbVec2s SoWin::getWidgetSize ( const HWND widget)
static

This method is provided for easier porting/compatibility with the Open Inventor SoXt component classes. It will call GetWindowExtEx() on the provided widget window handle's device context (returning an SbVec2s).

See also
setWidgetSize()

◆ hide()

void SoWin::hide ( HWND const widget)
static

This method is provided for easier porting/compatibility with the Open Inventor SoXt component classes. It will call ShowWindow() with the argument SW_HIDE on the provided widget window handle.

See also
show()

◆ init() [1/3]

HWND SoWin::init ( const char * appname,
const char * classname = "SoWin" )
static

This function initializes the SoWin library, as well as the Inventor API. The latter is done by calling SoDB::init(), SoNodeKit::init() and SoInteraction::init().

The returned HWND is a top level 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 SoWin::init() method below.

◆ init() [2/3]

void SoWin::init ( HWND toplevelwidget)
static

This function initializes the SoWin 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.

◆ init() [3/3]

HWND SoWin::init ( int & argc,
char ** argv,
const char * appname,
const char * classname = "SoWin" )
static

This function initializes the SoWin 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 HWND is a top level shell widget for the application, which can be used as a shell for the main component.

◆ isCompatible()

SbBool SoWin::isCompatible ( unsigned int major,
unsigned int minor )
static

Returns TRUE if this version of the SoWin 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.

◆ isDebugLibrary()

SbBool SoWin::isDebugLibrary ( void )
static

Returns TRUE if this binary version of the SoWin 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.

◆ lockGL()

void SoWin::lockGL ( void )
static

This method locks other threads out from a code section until the caller thread invokes SoWin::unlockGL().

It is meant to protect several threads invoking OpenGL calls in parallel, in case the underlying OpenGL implementation is not multi-thread safe.

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

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

◆ mainLoop()

void SoWin::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 SoWin::done() to clean up static data.

◆ setFatalErrorHandler()

SoWin::FatalErrorCB * SoWin::setFatalErrorHandler ( SoWin::FatalErrorCB * cb,
void * userdata )
static

Set up a callback to be invoked in the case of unexpected fatal error conditions within the SoWin 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 SoWin 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 SoWin library.

If no callback is explicitly set up by the application, the SoWin 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().)

◆ setWidgetSize()

void SoWin::setWidgetSize ( HWND const widget,
const SbVec2s size )
static

This method is provided for easier porting of applications based on the Open Inventor SoXt component classes. It will call SetWindowPos() on the provided widget window handle.

See also
getWidgetSize()

◆ show()

void SoWin::show ( HWND const widget)
static

This method is provided for easier porting/compatibility with the Open Inventor SoXt component classes. It will call ShowWindow() with the argument SW_SHOW on the provided widget window handle.

See also
hide()

◆ unlockGL()

void SoWin::unlockGL ( void )
static

See documentation for SoWin::lockGL().

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

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


The documentation for this class was generated from the following files: