NAME

       SoXt — routines for Inventor/Xt compatibility.

INHERITS FROM

       SoXt

SYNOPSIS

       #include <Inventor/Xt/SoXt.h>

          Methods from class SoXt:

     static Widget        init(const char *appName, const char *className = "Inventor")
     static void          init(Widget topLevelWidget)
     static void          mainLoop()
     static void          nextEvent(XtAppContext appContext, XEvent *event)
     static Boolean       dispatchEvent(XEvent *event)
     static XtAppContext  getAppContext()
     static Display *     getDisplay()
     static Widget        getTopLevelWidget()
     static void          show(Widget widget)
     static void          hide(Widget widget)
     static XmString      encodeString(char *s)
     static char *        decodeString(XmString xs)
     static void          setWidgetSize(Widget w, const SbVec2s &size)
     static SbVec2s       getWidgetSize(Widget w)
     static Widget        getShellWidget(Widget w)
     static   void          createSimpleErrorDialog(Widget   widget,   char   *dialogTitle,  char
                               *errorStr1, char *errorStr2 = NULL)
     static void          getPopupArgs(Display *d, int scr, 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)

DESCRIPTION

       The SoXt class initializes Inventor for use with the Xt toolkit  and  Motif.  SoXt::init()
       must  be  called  in order for Inventor to work properly with Xt. SoXt::mainLoop() must be
       called in order for extension device events to be passed to  Inventor  render  areas.  The
       other methods are convenience functions.

       Refer  to  the  SoXtComponent man pages for examples on how this class should be used when
       using Inventor Xt components.

METHODS

     static Widget        init(const char *appName, const char *className = "Inventor")
          This is called to initialize Inventor and Xt, and bind Inventor with Xt event  handling
          so  that Inventor sensors will work correctly. This returns the top level shell widget.
          This  method  will  call  SoDB::init(),  SoNodeKit::init(),  SoInteraction::init()  and
          XtAppInitialize().

     static void          init(Widget topLevelWidget)
          This  alternate form of init allows the application to initialize Xt. The passed widget
          should be the top level shell widget returned from the Xt initializiation. This  method
          will call SoDB::init(), SoNodeKit::init(), SoInteraction::init() and XtAppInitialize().

     static void          mainLoop()
          This retrieves and dispatches events (loops forever). Unlike Xt which ignores extension
          devices (i.e. any device besides mouse and keyboard),  this  main  loop  will  dispatch
          events  from input extension devices like the spaceball. It calls SoXt::nextEvent() and
          SoXt::dispatchEvent() to do this. If only the mouse and keyboard devices are used, this
          is equivalent to calling XtAppMainLoop().

     static void          nextEvent(XtAppContext appContext, XEvent *event)
          Get  the  nextEvent  by  calling XtAppNextEvent(). The appContext can be had by calling
          SoXt::getAppContext().

     static Boolean       dispatchEvent(XEvent *event)
          Dispatch the passed event to a handler. Mouse and keyboard  events  are  dispatched  by
          calling  XtDispatchEvent().  Events from input extension devices are dispatched by code
          implemented in this routine. This returns True if a handler was found, else it  returns
          False.

     static XtAppContext  getAppContext()
     static Display *     getDisplay()
     static Widget        getTopLevelWidget()
          These return information based on the top level widget returned by or passed to init.

     static void          show(Widget widget)
     static void          hide(Widget widget)
          Convenience routines to show and hide the passed widget.

          For  a  shell  widget,  this is equivalent to calling RealizeWidget() + XMapWindow() or
          XMapRaised() if window already exists (raise and de-iconify).  hide()  will  then  call
          XUnmapWindow().

          For a subwidget, those simply calls XtManageChild() and XtUnmanageChild().

     static XmString      encodeString(char *s)
     static char *        decodeString(XmString xs)
          These  are  convenience  routines  for  encoding a character string as an XmString, and
          decoding an XmString back to a character string. (XmString  is  a  Motif  string).  The
          application is responsible for freeing up the memory pointed to by these return values.
          Use XmStringFree() to free an XmString, and free() to free a character pointer.

     static void          setWidgetSize(Widget w, const SbVec2s &size)
     static SbVec2s       getWidgetSize(Widget w)
          Convenience routines to set/get the size of the given widget. Those are  equivalent  to
          calling XtSetValues() and XtGetValues() on XtNheight and XtNwidth widget resources.

     static Widget        getShellWidget(Widget w)
          Convenience  routine which will return the ShellWidget containing the given widget. The
          widget tree is traversed up until a shell widget is found using XtIsShell().

     static  void          createSimpleErrorDialog(Widget   widget,   char   *dialogTitle,   char
                               *errorStr1, char *errorStr2 = NULL)
          Convenience  routine  which brings a simple motif error dialog box displaying the given
          error string(s) and window title. The OK button, which destroys the dialog, is the only
          button  displayed.  The widget argument is used to create and center the dialog ( using
          XmCreateErrorDialog()).

     static void          getPopupArgs(Display *d, int scr, ArgList args, int *n)
          Convenience routine which gets visual args for the popup planes. These args can then be
          passed in to XmCreatePulldownMenu() or XmCreatePopupMenu() to create menus in the popup
          planes. registerColormapLoad() must be  called  for  each  pulldown  menu  to  properly
          load/unload the overlay color map on the shell when needed.

     static void          registerColormapLoad(Widget widget, Widget shell)
          Convenience  routine  which  will  register  map/unmap callbacks to load and unload the
          pulldown menu color map right before the menu is about to be  posted.  This  should  be
          called  when creating pulldown or popup menus in the overlays. This will make sure that
          the right color map is loaded into the shell widget (to make  the  pulldown/popup  look
          right)  and  remove  it  when  no longer needed (to make sure the OpenGL overlay widget
          color map is correctly loaded for 8 bit machines).

     static void          addColormapToShell(Widget widget, Widget shell)
     static void          removeColormapFromShell(Widget widget, Widget shell)
          Convenience routine to insert/remove the given widget colormap onto the supplied  shell
          widget.  This  will  not replace the existing installed colormaps (or list of windows),
          but  instead  insert  the  new  colormap   first   into   the   existing   list   using
          XGetWMColormapWindows() and XSetWMColormapWindows().

SEE ALSO

       SoXtComponent

                                                                                      SoXt(3IV)()