Main Page   Modules   Compound List   File List   Compound Members  

SoXt Class Reference

The SoXt class takes care of Xt initialization and event dispatching. More...

#include <Inventor/Xt/SoXt.h>

List of all members.

Public Types

enum  FatalErrors { NO_OPENGL_CANVAS = 0, INTERNAL_ASSERT, UNSPECIFIED_ERROR }

Public Methods

typedef void FatalErrorCB (const SbString errmsg, SoXt::FatalErrors errcode, void *userdata)

Static Public Methods

Widget init (const char *appname, const char *classname="SoXt")
Widget init (int argc, char **argv, const char *appname, const char *classname="SoXt")
void init (Widget toplevelwidget)
void mainLoop (void)
void exitMainLoop (void)
Widget getTopLevelWidget (void)
Widget getShellWidget (const Widget w)
void show (Widget const widget)
void hide (Widget const widget)
void setWidgetSize (Widget const widget, const SbVec2s size)
SbVec2s getWidgetSize (const Widget widget)
void createSimpleErrorDialog (Widget 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 (SoXt::FatalErrorCB *cb, void *userdata)

Static Protected Methods

SbBool isDebugLibrary (void)
SbBool isCompatible (unsigned int major, unsigned int minor)
SoXtABIType getABIType (void)
void abort (SoXtABIError error)


Detailed Description

The SoXt class takes care of Xt 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 SoXt library. Typical usage is as follows (complete application code):

#include <Inventor/Xt/SoXt.h>
#include <Inventor/Xt/viewers/SoXtExaminerViewer.h>
#include <Inventor/nodes/SoCube.h>

int
main(int argc, char **argv)
{
  // Initialize SoXt and Open Inventor libraries. This returns a main
  // window to use.
  Widget mainwin = SoXt::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.
  SoXtExaminerViewer * eviewer = new SoXtExaminerViewer(mainwin);
  eviewer->setSceneGraph(cube);
  eviewer->show();

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

See also:
SoXtComponent


Member Enumeration Documentation

enum SoXt::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 SoXt 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

Widget SoXt::init const char * appname,
const char * classname = "SoXt"
[inline, static]
 

This function initializes the SoXt library.

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.

void SoXt::init Widget toplevel [inline, static]
 

This function initializes the SoXt library.

It should be called for applications that want to create the toplevel shell widget themselves.

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

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 parent,
const char * title,
const char * string1,
const char * string2 = NULL
[static]
 

This function creates a simple error dialog window and places it on the display over the given parent widget.

If parent is NULL, the main toplevel widget of the application will be used.

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.

void SoXt::FatalErrorCB const SbString errmsg,
SoXt::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 SoXt::setFatalErrorHandler().

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, protected]
 

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, protected]
 

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.

SoXtABIType SoXt::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 SoXt::abort SoXtABIError 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 SoXt 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.


The documentation for this class was generated from the following files:
Generated at Tue Mar 5 03:33:04 2002 for SoXt by doxygen1.2.9 written by Dimitri van Heesch, © 1997-2001