SoGtk class Reference

List of all members.

Public Types
enum	FatalErrors { NO_OPENGL_CANVAS = 0, INTERNAL_ASSERT, UNSPECIFIED_ERROR }
Public Methods
typedef void	FatalErrorCB (const SbString errmsg, SoGtk::FatalErrors errcode, void *userdata)
Static Public Methods
GtkWidget *	init (const char appname, const char classname="SoGtk")
GtkWidget *	init (int argc, char *argv, const char appname, const char *classname="SoGtk")
void	init (GtkWidget *toplevelwidget)
void	mainLoop (void)
void	exitMainLoop (void)
GtkWidget *	getTopLevelWidget (void)
GtkWidget *	getShellWidget (const GtkWidget *w)
void	show (GtkWidget *const widget)
void	hide (GtkWidget *const widget)
void	setWidgetSize (GtkWidget *const widget, const SbVec2s size)
SbVec2s	getWidgetSize (const GtkWidget *widget)
void	createSimpleErrorDialog (GtkWidget widget, const char dialogTitle, const char errorStr1, const char errorStr2=NULL)
void	getVersionInfo (int major=NULL, int minor=NULL, int *micro=NULL)
const char *	getVersionString (void)
FatalErrorCB *	setFatalErrorHandler (SoGtk::FatalErrorCB cb, void userdata)
Static Protected Methods
SbBool	isDebugLibrary (void)
SbBool	isCompatible (unsigned int major, unsigned int minor)
SoGtkABIType	getABIType (void)
void	abort (SoGtkABIError error)

Detailed Description

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 SoGtk library. Typical usage is as follows (complete application code):

#include <Inventor/Gtk/SoGtk.h>
#include <Inventor/Gtk/viewers/SoGtkExaminerViewer.h>
#include <Inventor/nodes/SoCube.h>

int
main(int argc, char **argv)
{
  // Initialize SoGtk and Open Inventor libraries. This returns a main
  // window to use.
  GtkWidget * mainwin = SoGtk::init(argv[0]);

   // Make a dead simple scene graph, only containing a single cube.
  SoCube * cube = new SoCube;

  // Use one of the convenient viewer classes.
  SoGtkExaminerViewer * eviewer = new SoGtkExaminerViewer(mainwin);
  eviewer->setSceneGraph(cube);
  eviewer->show();

  // Pop up the main window.
  SoGtk::show(mainwin);
  // Loop until exit.
  SoGtk::mainLoop();
  return 0;
}

Member Enumeration Documentation

enum SoGtk::FatalErrors

Numerical identifiers for classifying the different kinds of possible fatal errors.

Enumeration values:

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 SoGtk library itself.
UNSPECIFIED_ERROR	Signifies that we were not able to specify in any greater detail the error condition that came up.

Member Function Documentation

GtkWidget * SoGtk::init	(	const char *	appname,

		const char *	classname = "SoGtk"
	)	`[inline, static]`

This function initializes the SoGtk library.

The returned GtkWidget * 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 SoGtk::init() method below.

void SoGtk::mainLoop ( void ) [static]

This is the event dispatch loop. It doesn't return until QApplication::quit() or QApplication::exit() is called (which is also done automatically by Gtk whenever the user closes an application's main widget).

void SoGtk::exitMainLoop ( void ) [static]

This method tells the GTK+ main processing loop to exit, which will give control back to the application again.

GtkWidget * SoGtk::getTopLevelWidget ( void ) [static]

Returns a pointer to the GtkWidget which is the main widget for the application. When this widget gets closed, SoGtk::mainLoop() will return (unless the close event is caught by the user).

See also:: getShellWidget()

GtkWidget * SoGtk::getShellWidget ( const GtkWidget * widget ) [static]

Returns a pointer to the GtkWidget which is the top level widget for the given GtkWidget 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 GtkWidget::topLevelWidget() method directly on w.

See also:: getTopLevelWidget()

void SoGtk::show ( GtkWidget *const widget ) [static]

This method is provided for easier porting/compatibility with the Open Inventor SoXt component classes. It will call gtk_widget_show() on the provided widget pointer.

See also:: hide()

void SoGtk::hide ( GtkWidget *const widget ) [static]

This method is provided for easier porting/compatibility with the Open Inventor SoXt component classes. It will call gtk_widget_hide() on the provided widget pointer.

See also:: show()

void SoGtk::setWidgetSize	(	GtkWidget *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 gtk_widget_set_usize on the provided w widget pointer.

See also:: getWidgetSize()

SbVec2s SoGtk::getWidgetSize ( const GtkWidget * widget ) [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 SoGtk::createSimpleErrorDialog	(	GtkWidget *	widget,

		const char *	dialogTitle,

		const char *	errorStr1,

		const char *	errorStr2 = NULL
	)	`[static]`

This will pop up an error dialog. It's just a simple wrap-around for the Gtk MessageBox::warning() call, provided for easier porting from applications using the Open Inventor SoXt component classes.

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.

dialogTitle is the title of the dialog box. errorStr1 and errorStr2 contains the text which will be shown in the dialog box.

There will only be a single "Ok" button for the user to press.

void SoGtk::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 SoGtk 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 * SoGtk::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.

void SoGtk::FatalErrorCB	(	const SbString	errmsg,

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

SoGtk::FatalErrorCB * SoGtk::setFatalErrorHandler	(	SoGtk::FatalErrorCB *	cb,

		void *	userdata
	)	`[static]`

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

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

Returns TRUE if this binary version of the SoGtk 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 SoGtk::isCompatible	(	unsigned int	major,

		unsigned int	minor
	)	`[static, protected]`

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

SoGtkABIType SoGtk::getABIType ( void ) [static, protected]

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 SoGtk::abort ( SoGtkABIError error ) [static, protected]

Abort the application due to some kind of mismatch in the ABI settings / configuration. This should hopefully help application programmers avoid shooting themselves in the foot by controlling certain run-time parameters in the client application versus what is expected by the SoGtk library.

If you're an application programmer, it is very likely that you only need to consider this an internal library method.

This method was not part of the original SGI InventorXt library, but is an extension specific to the Coin project.

SoGtk Class Reference

Public Types

Public Methods

Static Public Methods

Static Protected Methods

Detailed Description

Member Enumeration Documentation

Member Function Documentation