Routines for Open Inventor/Windows compatibility. More...

#include <Inventor/Win/SoWin.h>

Static Public Member Functions
static SoWidget	init (const char appName, const char className="Inventor")
	This is called to initialize Open Inventor and Windows, and bind Open Inventor with Windows message handling so that Open Inventor sensors will work correctly.

static void	init (SoWidget topLevelWidget)
	This alternate form of init allows the application to initialize Windows.

static void	init ()
	This alternate form of init does not require a top level window.

static bool	isInitialized ()
	Returns TRUE if SoWin module is currently initialized.

static void	finish ()
	Frees Open Inventor's internal static memory allocations.

static int	mainLoop ()
	Enters the main event loop and waits until exit() is called or a WM_QUIT message is sent to the message queue.

static void	exit (int returnCode=0)
	Tells the main event loop to exit with a return code.

static SbBool	nextEvent (XtAppContext appContext, XEvent *event)
	Get the nextEvent by calling GetMessage.

static Boolean	dispatchEvent (XEvent *event)
	Dispatch the passed message to a handler.

static XtAppContext	getAppContext ()
	This method is included for portability only.

static SbGlContextHelper::Display	getDisplay ()
	This method is included for portability only.

static SoWidget	getTopLevelWidget ()
	Returns information based on the initial window handle returned by or passed to init.

static void	show (SoWidget w)
	Convenience routine to show the passed window handle.

static void	hide (SoWidget w)
	Convenience routine to hide the passed window handle.

static XmString	encodeString (char *s)
	This method is included for portability only.

static char *	decodeString (XmString xs)
	This method is included for portability only.

static void	setWidgetSize (SoWidget w, const SbVec2s &size)
	Convenience routine to set the size of the given window.

static SbVec2s	getWidgetSize (SoWidget w)
	Convenience routine to get the size of the given window.

static SoWidget	getShellWidget (SoWidget w)
	Convenience routine which will return the topmost window containing the given window handle.

static void	createSimpleErrorDialog (SoWidget widget, char dialogTitle, char errorStr1, char *errorStr2=NULL)
	Convenience routine which brings a simple Windows error dialog box displaying the given error string(s) and window title.

static void	getPopupArgs (UINT d, int scr, ArgList args, int n)
	This method is included for portability only.

static void	addColormapToShell (SoWidget widget, SoWidget shell)
	This method is included for portability only.

static SoConsole *	getErrorConsole (void)
	Returns the VSG error console.

static void	doIdleTasks (void)
	If you use SoWin::mainLoop or SoWin::nextEvent, Inventor automatically calls this when the Windows message queue is empty.

Deprecated

static SoDEPRECATED SoWidget	threadInit (const char appName, const char className="Inventor")
	This method calls XXX::threadInit(), rather than XXX::init().

static SoDEPRECATED void	threadInit (SoWidget topLevelWidget)
	This method calls XXX::threadInit(), rather than XXX::init().

static SoDEPRECATED void	threadInit ()
	This method calls XXX::threadInit(), rather than XXX::init().

Detailed Description

Routines for Open Inventor/Windows compatibility.

The SoWin class initializes Open Inventor for use with Microsoft Windows. SoWin::init() must be called in order for Open Inventor to work properly with Windows. SoWin::finish() should be called to clean up static memory allocations.

SoWin::mainLoop() must be called in order for extension device messages to be passed to Open Inventor render areas. The other methods are convenience functions.

Refer to the SoWinComponent reference pages for examples on how this class should be used when using Open Inventor Windows components.

Member Function Documentation

◆ addColormapToShell()

static void SoWin::addColormapToShell	(	SoWidget	widget,
		SoWidget	shell
	)

static

This method is included for portability only.

◆ createSimpleErrorDialog()

static void SoWin::createSimpleErrorDialog	(	SoWidget	widget,
		char *	dialogTitle,
		char *	errorStr1,
		char *	errorStr2 = `NULL`
	)

static

Convenience routine which brings a simple Windows error dialog box displaying the given error string(s) and window title.

The OK button, which destroys the dialog, is the only button displayed.

◆ decodeString()

static char * SoWin::decodeString ( XmString xs )

static

This method is included for portability only.

◆ dispatchEvent()

static Boolean SoWin::dispatchEvent ( XEvent * event )

static

Dispatch the passed message to a handler.

This returns TRUE if a handler was found, else it returns FALSE.

◆ doIdleTasks()

static void SoWin::doIdleTasks ( void )

static

If you use SoWin::mainLoop or SoWin::nextEvent, Inventor automatically calls this when the Windows message queue is empty.

If you don't use those utilities you are responsible for periodically processing the tasks in the Inventor "delay queue", *** some of which are critical! *** like notifying the viewer when the scene graph changes.

◆ encodeString()

static XmString SoWin::encodeString ( char * s )

static

This method is included for portability only.

◆ exit()

static void SoWin::exit ( int returnCode = 0 )

static

Tells the main event loop to exit with a return code.

After this function has been called, the mainLoop() function returns returnCode. If the event loop is not running, this function does nothing.

By convention, a returnCode of 0 means success, and any non-zero value indicates an error.

◆ finish()

static void SoWin::finish ( )

static

Frees Open Inventor's internal static memory allocations.

This avoids false positives from memory leak checking software. We recommend calling this method and it should be the last Open Inventor method called by the application. This method calls SoDB::finish(), SoNodeKit::finish(), and SoInteraction::finish().

Note: Open Inventor objects should be destroyed before you call this method. For example:

Wrong Open Inventor Ending

Safe Open Inventor Endings

void main() {
  SoWidget myW = SoWin::init("");
  SoWinExaminerViewer viewer( myW );
  ....
  ....
  SoWin::mainLoop();
  SoWin::finish();
}

void runApp() {
  SoWinExaminerViewer viewer( myW );
  ....
  ....
  SoWin::mainLoop();
}
 
void main () {
  SoWidget myW = SoWin::init("");
  runApp();
  SoWin::finish();
}

void main () {
  SoWidget myW = SoWin::init("");
  SoWinExaminerViewer* viewer
         = new SoWinExaminerViewer( myW );
  ....
  ....
  SoWin::mainLoop();
  delete viewer;
  SoWin::finish();
 }

SoWin doesn't end properly: SoWinExaminerViewer is destroyed after the finish() method has been called.

The SoWinExaminerViewer (that uses Open Inventor) is destroyed before the finish() method is called.

◆ getAppContext()

static XtAppContext SoWin::getAppContext ( )

static

This method is included for portability only.

◆ getDisplay()

static SbGlContextHelper::Display SoWin::getDisplay ( )

static

This method is included for portability only.

◆ getErrorConsole()

static SoConsole * SoWin::getErrorConsole ( void )

static

Returns the VSG error console.

An application can use the VSG error console to display its own text messages. See SoConsole for details.

◆ getPopupArgs()

static void SoWin::getPopupArgs	(	UINT *	d,
		int	scr,
		ArgList	args,
		int *	n
	)

static

This method is included for portability only.

◆ getShellWidget()

static SoWidget SoWin::getShellWidget ( SoWidget w )

static

Convenience routine which will return the topmost window containing the given window handle.

The window handle tree is traversed up until the last window handle is found using GetParent.

◆ getTopLevelWidget()

static SoWidget SoWin::getTopLevelWidget ( )

static

Returns information based on the initial window handle returned by or passed to init.

◆ getWidgetSize()

static SbVec2s SoWin::getWidgetSize ( SoWidget w )

static

Convenience routine to get the size of the given window.

◆ hide()

static void SoWin::hide ( SoWidget w )

static

Convenience routine to hide the passed window handle.

This includes any children the window may have.

◆ init() [1/3]

static void SoWin::init ( )

static

This alternate form of init does not require a top level window.

Calls SoDB::init(), SoNodeKit::init(), and SoInteraction::init().

◆ init() [2/3]

static SoWidget SoWin::init	(	const char *	appName,
		const char *	className = `"Inventor"`
	)

static

This is called to initialize Open Inventor and Windows, and bind Open Inventor with Windows message handling so that Open Inventor sensors will work correctly.

Use this method for convenience if you want Open Inventor to create a top-level window for the application. Returns the top level shell window handle. Calls SoDB::init(), SoNodeKit::init(), and SoInteraction::init().

◆ init() [3/3]

static void SoWin::init ( SoWidget topLevelWidget )

static

This alternate form of init allows the application to initialize Windows.

TopLevelWidget should be the top level window handle returned from the Windows initialization.
Calls SoDB::init(), SoNodeKit::init(), and SoInteraction::init().

◆ isInitialized()

static bool SoWin::isInitialized ( )

static

Returns TRUE if SoWin module is currently initialized.

◆ mainLoop()

static int SoWin::mainLoop ( )

static

Enters the main event loop and waits until exit() is called or a WM_QUIT message is sent to the message queue.

Returns the value that was passed to exit() or the WM_QUIT message.

It calls nextEvent() and dispatchEvent() to retrieve and dispatch events.

◆ nextEvent()

static SbBool SoWin::nextEvent	(	XtAppContext	appContext,
		XEvent *	event
	)

static

Get the nextEvent by calling GetMessage.

The appContext can be had by calling SoWin::getAppContext().

◆ setWidgetSize()

static void SoWin::setWidgetSize	(	SoWidget	w,
		const SbVec2s &	size
	)

static

Convenience routine to set the size of the given window.

◆ show()

static void SoWin::show ( SoWidget w )

static

Convenience routine to show the passed window handle.

This includes any children the window may have.

◆ threadInit() [1/3]

static SoDEPRECATED void SoWin::threadInit ( )

static

This method calls XXX::threadInit(), rather than XXX::init().

Otherwise it is the same as the corresponding SoWin::init() method. Use this method if you need to use multi-threading with Open Inventor.

◆ threadInit() [2/3]

static SoDEPRECATED SoWidget SoWin::threadInit	(	const char *	appName,
		const char *	className = `"Inventor"`
	)

static

This method calls XXX::threadInit(), rather than XXX::init().

Otherwise it is the same as the corresponding SoWin::init() method. Use this method if you need to use multi-threading with Open Inventor.

◆ threadInit() [3/3]

static SoDEPRECATED void SoWin::threadInit ( SoWidget topLevelWidget )

static

This method calls XXX::threadInit(), rather than XXX::init().

Otherwise it is the same as the corresponding SoWin::init() method. Use this method if you need to use multi-threading with Open Inventor.

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

Inventor/Win/SoWin.h

Open Inventor Release 2023.2.3

Static Public Member Functions

Detailed Description

SEE ALSO

Member Function Documentation

◆ addColormapToShell()

◆ createSimpleErrorDialog()

◆ decodeString()

◆ dispatchEvent()

◆ doIdleTasks()

◆ encodeString()

◆ exit()

◆ finish()

◆ getAppContext()

◆ getDisplay()

◆ getErrorConsole()

◆ getPopupArgs()

◆ getShellWidget()

◆ getTopLevelWidget()

◆ getWidgetSize()

◆ hide()

◆ init() [1/3]

◆ init() [2/3]

◆ init() [3/3]

◆ isInitialized()

◆ mainLoop()

◆ nextEvent()

◆ setWidgetSize()

◆ show()

◆ threadInit() [1/3]

◆ threadInit() [2/3]

◆ threadInit() [3/3]