Nodes with a grouping behavior are the SoTopLevelDialog^{( C++ )}, SoMenuBar^{( C++ )}, and SoMenuPopup^{( C++ )} nodes, and the SoDialogGroup^{( C++ )} -derived classes SoColumnDialog^{( C++ )}, SoRowDialog^{( C++ )}, and SoTabDialog^{( C++ )}. (The launcher classes are explained next). These different containers can be used together to create a well-organized interface.

To add a child to these classes, simply use the addChild() method similar to an SoGroup^{( C++ | Java | .NET )} node. All other SoGroup^{( C++ | Java | .NET )} methods like insertChild(), replaceChild(), ..., are available as well.

	Careful, although these classes have similar methods, they do not inherit from the SoGroup( C++ | Java | .NET ) class.

Each one of these nodes manages its own children. Container nodes can be nested to create more complex groupings.

SoRowDialog^{( C++ )} manages the position of its children to make rows: it puts one child beneath the other. When resizing, the SoRowDialog^{( C++ )} component resizes all its children according to the constraints on them. The size difference between the initial and final size is evenly distributed.

SoColumnDialog^{( C++ )} manages the position of its children to make columns: the children are placed side by side.

SoTabDialog^{( C++ )} organizes its children by pages. This component can be very useful when there are a large number of controls that would not fit well on a single page.

SoTopLevelDialog^{( C++ )} has the same managing behavior as SoRowDialog^{( C++ )}. The difference is that SoTopLevelDialog^{( C++ )} can have a child (only one) of type SoMenuBar^{( C++ )} and some other children of type SoDialogComponent^{( C++ )}. If an SoMenuBar^{( C++ )} child exists, a menu bar is built at the top of the window. The SoMenuBar^{( C++ )} can have children of type SoMenuPopup^{( C++ )} which constitute the sub-menus. The items of the menu will be children of the SoMenuPopup^{( C++ )} nodes.

The first way to create and use a DialogViz interface is to load it from an Inventor file. Simply use the SoDialogViz::loadFromFile(SbString filename, SbString auditorID) method to load your DialogViz tree.

This method take two arguments:

For example, to generate the following DialogViz window:

Figure 29.4.  Simple dialog box

#Inventor V2.1 ascii

TopLevelDialog
  {
  ColumnDialog
    {
    DialogPushButton
      {
      buttonLabel "OK"
      }
    DialogPushButton
      {
      buttonLabel "Cancel"
      }
    }
  }


       

...

Widget myWindow = SoXt::init();
SoDialogViz::init();

...

SoTopLevelDialog* myDialog = (SoTopLevelDialog*)
SoDialogViz::loadFromFile("myInventorFile.iv");
myDialog->buildDialog(myWindow, TRUE);
myDialog->show();
...

       

See the section called “2D/3D Differences” for more information about the buildDialog() method.

A DialogViz interface can also be built programmatically, just like you would build an ordinary Open Inventor scene graph.

To create a dialog window,

For example, the following source code builds the same dialog box window as shown in Figure 29.4, “ Simple dialog box”.

...

Widget myWindow = SoXt::init();
SoDialogViz::init();

...

SoTopLevelDialog* myDialog = new SoTopLevelDialog();

SoColumnDialog* myCol = new SoColumnDialog();

SoDialogPushButton* myOKButton = new SoDialogPushButton();
myOKButton->buttonLabel = "OK";
myCol->addChild(myOKButton);

SoDialogPushButton* myCancelButton = new SoDialogPushButton();
myCancelButton->buttonLabel = "Cancel";
myCol->addChild(myCancelButton);
myDialog->addChild(myCol);

myDialog->buildDialog(myWindow, TRUE);
myDialog->show();

...

         

The way to build a 2D and a 3D DialogViz interface is the same, but some rules must be followed for the two cases:

The launcher components have been developed to simplify utilization for programmers. The goal of the launcher is to directly load a new SoTopLevelDialog^{( C++ )} component when it is activated. This is useful primarily when you want to open other dialog windows in the application that are configuration windows or other special-purpose windows that don’t always need to be visible. The presence of the launcher allows the programmer to avoid having to develop an auditor class (See Section 29.3, “Interacting with Your Application” for more details on creating and using auditors) to handle the activation of a control that would be dedicated to open a new window

The scene graph above allows the “TopLevelDialog 1” dialog box to be shown by triggering a push button “PushButtonLauncher”. By changing the check box “CheckBoxLauncher” state, the dialog windows “TopLevelDialog 2” and “TopLevelDialog 3” are launched or hidden at the same time.

SoDialogCustom^{( C++ )} was created to map any widgets you want to see in a dialog window. For example, it’s very interesting to be able to embed an Open Inventor viewer in the same window with the user interface controls.

The next steps show you how to include a viewer in a DialogViz window:

Here is some sample code:

...
myTopLevelDialog->buildDialog(mainWindow, TRUE);
myTopLevelDialog->show();

// retrieve the DialogCustom in dialog scene graph
customNode = (SoDialogCustom*)
myTopLevelDialog->searchForAuditorId(SbString("theCustom"));

SoXtExaminerViewer *myViewer = new SoXtExaminerViewer(customNode->getWidget());
...
        

This allows you to build an advanced interface that could look like:

Figure 29.5. Use of DialogViz within a VolumeViz demo