SoXt: SoXt Class Reference

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

  #include <Inventor/Xt/SoXt.h>
  #include <Inventor/Xt/viewers/SoXtExaminerViewer.h>
  #include <Inventor/nodes/SoBaseColor.h>
  #include <Inventor/nodes/SoCone.h>
  #include <Inventor/nodes/SoSeparator.h>
  
  int
  main(int argc, char ** argv)
  {
    // Initialize SoXt and Inventor API libraries. This returns a main
    // window to use.
    Widget mainwin = SoXt::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.
    SoXtExaminerViewer * eviewer = new SoXtExaminerViewer(mainwin);
    eviewer->setSceneGraph(root);
    eviewer->show();
  
    // Pop up the main window.
    SoXt::show(mainwin);
    // Loop until exit.
    SoXt::mainLoop();

    // Clean up resources.
    delete eviewer;
    root->unref();

    return 0;
  }

Member Typedef Documentation

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

Member Enumeration Documentation

enum SoXt::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 SoXt library itself.

enum SoXt::ABIType

Numerical identifiers to identify how the library was built.

Enumerator:

DLL	The SoXt library was built as a dynamic link library (aka "shared library").
LIB	The SoXt library was built as a static library.
UNKNOWN	The SoXt introspection mechanisms can not decide how the library was built.

Member Function Documentation

Widget SoXt::init	(	const char *	appname,
		const char *	classname = `"SoXt"`
	)			`[static]`

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

The returned Widget 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 SoXt::init() method below.

Widget SoXt::init	(	int &	argc,
		char **	argv,
		const char *	appname,
		const char *	classname = `"SoXt"`
	)			`[static]`

This function initializes the SoXt 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 Widget is a toplevel shell widget for the application, which can be used as a shell for the main component.

void SoXt::init ( Widget toplevelwidget ) [static]

This function initializes the SoXt 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 SoXt::mainLoop ( void ) [static]

This function should be used instead of XtAppMainLoop(). The current implementation is no different than the standard event loop, but in the future it will add support for input device extensions.

If you need your own event dispatching loop, base your code on this one, and use SoXt::dispatchEvent() when appropriate.

void SoXt::exitMainLoop ( void ) [static]

This method makes the event loop stop processing events and exit so the program can finish.

This is an SoXt extension not found in InventorXt.

See also:: SoXt::mainLoop

void SoXt::done ( void ) [static]

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

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

Widget SoXt::getTopLevelWidget ( void ) [static]

This function returns the toplevel shell for the application.

Widget SoXt::getShellWidget ( const Widget widget ) [static]

This function returns the shell of the given widget.

void SoXt::show ( Widget const widget ) [static]

This function realizes the given widget.

void SoXt::hide ( Widget const widget ) [static]

This function hides the given widget.

void SoXt::setWidgetSize	(	Widget const	widget,
		const SbVec2s	size
	)			`[static]`

This function resizes the widget to the given size.

SbVec2s SoXt::getWidgetSize ( const Widget widget ) [static]

This function returns the size of the given widget.

void SoXt::createSimpleErrorDialog	(	Widget	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 SoXt::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 SoXt 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 * SoXt::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 * SoXt::getVersionToolkitString ( void ) [static]

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

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

SoXt::FatalErrorCB * SoXt::setFatalErrorHandler	(	SoXt::FatalErrorCB *	cb,
		void *	userdata
	)			`[static]`

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

If no callback is explicitly set up by the application, the SoXt 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 SoXt::isDebugLibrary ( void ) [static]

Returns TRUE if this binary version of the SoXt 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 SoXt::isCompatible	(	unsigned int	major,
		unsigned int	minor
	)			`[static]`

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

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

void SoXt::lockGL ( void ) [static]

This method locks other threads out from a code section until the caller thread invokes SoXt::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 SOXT_ENTER_GL_SECTION().

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

void SoXt::unlockGL ( void ) [static]

See documentation for SoXt::lockGL().

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

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

void SoXt::nextEvent	(	XtAppContext	context,
		XEvent *	event
	)			`[static]`

This function calls XtAppNextEvent() to fill in the event structure with the next event for the given context.

Boolean SoXt::dispatchEvent ( XEvent * event ) [static]

This method dispatches the event by calling XtDispatchEvent(). Special handling of extension input devices will be handled in this method in the future.

XtAppContext SoXt::getAppContext ( void ) [static]

This function returns the Xt Application Context for the application.

Display * SoXt::getDisplay ( void ) [static]

This function returns the X Display of the application.

XmString SoXt::encodeString ( const char *const str ) [static]

Create and return a localized string from str.

The caller is responsible for freeing the returned XmString by using XmStringFree() or just plain XtFree((char *) str).

char * SoXt::decodeString ( XmString xstring ) [static]

Decode a left-to-right localized string into a simple character array, and return its memory pointer.

The caller is responsible for freeing the returned character string with XtFree() to avoid memory leaks.

void SoXt::getPopupArgs	(	Display *	display,
		int	screen,
		ArgList	args,
		int *	n
	)			`[static]`

This function should add the necessary arguments to the args argument list so the popup shell gets the same visual and colormap as the rest of the application.

This function is not implemented.

void SoXt::registerColormapLoad	(	Widget	widget,
		Widget	shell
	)			`[static]`

This function is not implemented.

void SoXt::addColormapToShell	(	Widget	widget,
		Widget	shell
	)			`[static]`

This function is not implemented.

void SoXt::removeColormapFromShell	(	Widget	widget,
		Widget	shell
	)			`[static]`

This function is not implemented.

void SoXt::addExtensionEventHandler	(	Widget	widget,
		int	type,
		XtEventHandler	proc,
		XtPointer	data
	)			`[static]`

This function adds an extension event handler to the application, which will be considered in the SoXt::mainLoop event dispatching loop.

See also:: SoXt::removeExtensionEventHandler(), SoXt::getExtensionEventHandler()

void SoXt::removeExtensionEventHandler	(	Widget	widget,
		int	type,
		XtEventHandler	proc,
		XtPointer	data
	)			`[static]`

This method removes an extension event handler.

See also:: SoXt::addExtensionEventHandler(), SoXt::getExtensionEventHandler()

void SoXt::getExtensionEventHandler	(	XEvent *	event,
		Widget &	widget,
		XtEventHandler &	proc,
		XtPointer &	data
	)			`[static, protected]`

This method returns the extension event handler for the given event.

See also:: SoXt::addExtensionEventHandler
SoXt::removeExtensionEventHandler


Public Types
typedef void	FatalErrorCB (const SbString errmsg, SoXt::FatalErrors errcode, void *userdata)
	UNSPECIFIED_ERROR = 0
	NO_OPENGL_CANVAS
	INTERNAL_ASSERT
	DLL
	LIB
	UNKNOWN
enum	FatalErrors { UNSPECIFIED_ERROR = 0, NO_OPENGL_CANVAS, INTERNAL_ASSERT }
enum	ABIType { DLL, LIB, UNKNOWN }
Static Public Member Functions
static Widget	init (const char appname, const char classname="SoXt")
static Widget	init (int &argc, char *argv, const char appname, const char *classname="SoXt")
static void	init (Widget toplevelwidget)
static void	mainLoop (void)
static void	exitMainLoop (void)
static void	done (void)
static Widget	getTopLevelWidget (void)
static Widget	getShellWidget (const Widget w)
static void	show (Widget const widget)
static void	hide (Widget const widget)
static void	setWidgetSize (Widget const widget, const SbVec2s size)
static SbVec2s	getWidgetSize (const Widget widget)
static void	createSimpleErrorDialog (Widget 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 (SoXt::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)
static void	nextEvent (XtAppContext, XEvent *)
static Boolean	dispatchEvent (XEvent *event)
static XtAppContext	getAppContext (void)
static Display *	getDisplay (void)
static XmString	encodeString (const char *const str)
static char *	decodeString (XmString xstring)
static void	getPopupArgs (Display display, int screen, ArgList args, int n)
static void	registerColormapLoad (Widget widget, Widget shell)
static void	addColormapToShell (Widget widget, Widget shell)
static void	removeColormapFromShell (Widget widget, Widget shell)
static void	addExtensionEventHandler (Widget widget, int eventType, XtEventHandler proc, XtPointer clientData)
static void	removeExtensionEventHandler (Widget widget, int eventType, XtEventHandler proc, XtPointer clientData)
Static Protected Member Functions
static void	getExtensionEventHandler (XEvent *event, Widget &widget, XtEventHandler &proc, XtPointer &clientData)
Friends
class	SoGuiP
class	SoXtP

SoXt Class Reference
[Miscellaneous Classes]

Detailed Description

Public Types

Static Public Member Functions

Static Protected Member Functions

Friends

Member Typedef Documentation

Member Enumeration Documentation

Member Function Documentation

SoXt Class Reference [Miscellaneous Classes]

Detailed Description

Public Types

Static Public Member Functions

Static Protected Member Functions

Friends

Member Typedef Documentation

Member Enumeration Documentation

Member Function Documentation

SoXt Class Reference
[Miscellaneous Classes]