Chapter 9 in The Inventor Mentor discusses the various actions that can be applied to a scene graph. One of these is the SoRayPickAction. When you click on a scene, SoRayPickAction projects a ray from the camera position through the scene. The result of applying an SoRayPickAction is an SoPickedPoint or an SoPickedPointList, which is a list of SoPickedPoints, sorted closest to farthest, as shown in the following diagram.

Figure 6-1. SoRayPickAction

An SoPickedPoint contains general information about the point that was picked, such as the coordinates and the surface normal at that point. It also provides a getDetail() method that returns more specific information regarding the picked object. In Molecular Inventor, when an SoRayPickAction is applied, the ChemDisplay node in a scene graph creates an instance of the ChemDetail class. It contains information about which atom, bond, atom label, or bond label was picked.

The getDetail() method returns a pointer to an instance of SoDetail. Therefore, you need to cast the pointer to an instance of ChemDetail in a fashion similar to the following:

const SoDetail *pickDetail = myPickedPoint->getDetail();
if (pickDetail != NULL && pickDetail->getTypeId() == 
    ChemDetail::getClassTypeId()) {

    int32_t atomIndex, bondIndex;
    ChemDetail *chemDetail = (ChemDetail *)pickDetail;
    chemDetail->getAtomBondIndex(atomIndex, bondIndex);
    if (atomIndex) != -1) {
    printf(“Atom %d picked\n”, atomIndex);
    }
        else if (bondIndex != -1) {
        printf(“Bond %d picked\n”, bondIndex);
    }
}

As shown in the example above, the get...() functions in ChemDetail return information regarding the items picked. All get...() functions return -1 if an item of a given type was not picked. The get...() methods are described in the following table:

ChemSelection is very similar in concept to the SoSelection node within Open Inventor (described in Chapter 10 in The Inventor Mentor). ChemSelection is a grouping node derived from SoSeparator and therefore has methods that manage the addition and removal of child nodes. ChemSelection also provides methods an application can invoke to programmatically select items, and selection mechanisms that allow the user of an application to interactively select items from the display. While ChemSelection can have as its children both MI and Open Inventor nodes, its selection mechanisms, both programmatic and interactive, only operate on MI nodes.

To use the selection mechanisms provided by a ChemSelection node, you must make the ChemSelection node the parent of all the other nodes in the scene graph or the subgraph that contains the items you want to allow the user to select.

Typically, there is only one ChemSelection node within a scene graph and its position is near the top of the scene graph. There can be any number of MI and Open Inventor nodes as children of a ChemSelection node. However, it is unadvisable to have a ChemSelection node as a child of another ChemSelection node due to possible conflicts in performing the selections. The simplest MI scene graph which employs the ChemSelection node is:

Figure 6-2. Making ChemSelection the Root Node

ChemSelection()
ChemSelection(int nChildren)

Interactive selection mechanisms provided by the ChemSelection node allow users to select all or part of a chemical system for an application-defined purpose. Additionally, an application can programmatically select and deselect items, for example, an application might programmatically select atoms with ID's numbered 5 through 10. The ChemDisplay node can automatically highlight the selected items according to values set within a ChemDisplayParam node, as shown in the following figure.

Figure 6-3. Selecting Part of a Molecule

Whether items are selected interactively or programmatically, ChemSelection places the selected items on a selection list. The selection list can be accessed by an application in order to take some appropriate action with the items on the list.

When one or more items are selected, ChemSelection stores information regarding the selected items in instances of the ChemPath class. A ChemPath is comprised of an SoPath, which is the list of nodes traversed in a selection process, and a set of indices, which store the atoms, bonds, atom labels and bond labels that were selected within the SoPath.

The SoPath portion of a ChemPath always begins with the ChemSelection node and always ends with the ChemDisplay node responsible for rendering the selected items. Therefore, the indices of the ChemPath specify the atoms, bonds, and labels that were selected within the particular ChemDisplay node.

Figure 6-4. ChemPath

To access the various portions of a ChemPath, you use the methods described in the following table:

ChemSelection implements four interactive selection mechanisms:

Users can select individual items by clicking the left mouse button while the cursor is on an item.

A lasso is a selection mechanism that appears as a user-defined shape, according to the movement of the mouse. The user draws the lasso by pressing the left mouse button, dragging the mouse around the part of the display of interest, and then releasing the mouse button. Even though the beginning and ending points of the lasso may be far apart, MI considers the ends connected. The items within the lasso are selected according to the lasso policy. The lasso policy defines when an item is considered to be selected; there are three options:

A drag rectangle is a lasso-type selection mechanism that appears as a rectangle when the user presses the left mouse button on anything other than an atom, drags the mouse over the part of the display of interest, and then releases the mouse button. The items within the rectangle are selected according to the lasso policy.

A selection sphere is a selection mechanism that appears as a sphere when a user presses the left mouse on an atom and drags the mouse. The radius of the sphere increases or decreases according to the mouse movement, much like the drag rectangle, except that the sphere is centered on an atom. In addition, as the sphere changes size, the value of its radius is displayed on the surface of the sphere. When the user releases the mouse button, the items within the sphere are selected according to the lasso policy.

Figure 6-6. Selection Sphere

Callback functions registered with ChemSelection can be invoked whenever a user performs a selection. The application can then access the current selection list and process the items on it. ChemDisplay can automatically highlight the selected items according to the values of the ChemDisplayParam fields. Alternatively, an application can provide customized highlighting.

root->addChild(chemSelection);

SbColor lassoColor(1, 1, 0);
examinerViewer->setOverlayColorMap(1, 1, &lassoColor);
examinerViewer->setSceneGraph(root);
examinerViewer->setOverlaySceneGraph(chemSelection->getSceneGraph());
examinerViewer->show();

The following sections describe how to set the ChemSelection fields that control various aspects of the interactive selection mechanisms.

chemSelection->parts.setValue(ChemSelection::ATOMS |
ChemSelection::BONDS);

Lasso Policy Settings

The atomLassoPolicy, bondLassoPolicy, atomLabelLassoPolicy, and bondLabelLassoPolicy fields determine what parts of an atom, bond, atom label, and bond label, respectively, must be inside a lasso, drag rectangle, or selection sphere to be selected.

---

Note: Although these fields are called lasso policies, they also apply to the selection sphere.

---

The atomLassoPolicy, bondLassoPolicy, atomLabelLassoPolicy, and bondLabelLassoPolicy fields are equal to one of the values in the LassoPolicy enum shown in the following table.

Table 6-5. LassoPolicy Values

LassoPolicy Value	Description
CENTER	The lasso must contain the center of an item.
THRU_BBOX	The lasso must pass through the bounding box of an item.
ENTIRE_BBOX	The lasso must enclose all points of the bounding box of an item.

A bounding box is box enclosing objects defined by a scene graph.

Lasso Rendering Settings

The lassoLineWidth, lassoLinePattern, and lassoLineColorIndex fields determine the appearance of the lasso and drag rectangle. lassoLineWidth defines the width of the lines; the default is 1. lassoLinePattern defines the stipple pattern used when drawing the lines; the default is solid: 0xFFFF. lassoLineColorIndex specifies the color of the rectangle. The field is the index value in the color table used by overlay planes; the default is 1.

---

Note: The valid values for lassoLineWidth and lassoLinePattern are the same as the valid values for the lineWidth and linePattern fields in an SoDrawStyle node.

---

The same methods that ChemSelection uses internally to work with the selection list when selections are made interactively are also available directly to an application. These methods allow the application to select, deselect, toggle, and merge specified ChemPaths.

void                  select(const ChemPath *path)
void                  deselect(ChemPath *path)
void                  deselect(int which)
void                  deselectAll()
void                  toggle(const ChemPath *path)
void                  merge(const ChemPath *path)
SbBool                isSelected(const ChemPath *path) const
SbBool                isSelected(SoNode *node) const
int                   getNumSelected() const
const ChemPathList *  getList() const
ChemPath *            getPath(int index) const
ChemPath *            operator [](int i) const

To use many of these methods, the application must first create a ChemPath.

The following table describes these methods. Keep in mind that a ChemPath is comprised of an SoPath and a set of indices for atoms, bonds, and labels. Also recall, that if the SoPath portion of the passed ChemPath is the same as one which already exists in the selection list, ChemPathList does not generate a new entry. Instead, it updates the indices of the existing ChemPath with those of the passed ChemPath in accordance with the method invoked. Therefore use care when invoking methods that use an entry in a selection list rather than a ChemPath.

void
mySelect()

{
    // Set up a SoSearchAction to look for the chemDisplay node in
    // the subgraph under chemSelection.  The result is a SoPath
    // which begins at chemSelection and ends at chemDisplay which is
    // needed for a valid ChemPath.
    SoSearchAction sa;
    sa.setFind(SoSearchAction::NODE);
    sa.setInterest(SoSearchAction::FIRST);
    sa.setNode((SoNode *)chemDisplay);
    sa.apply(chemSelection);
    if (sa.getPath() == NULL) {
        printf (“ChemDisplay not in path!!!\n”);
        return;
    }

    // Create a new ChemPath
    ChemPath *chemPath = new ChemPath;
    chemPath->ref();

    // Arbitrarily set the atom indices in the ChemPath to start at
    // index 10 and include a total of 10 entries.
    MFVec2i atomIndex;
    atomIndex.set1Value(0, 10, 10);
    if (!chemPath->setPath(sa.getPath(), &atomIndex, NULL, NULL, NULL)) {
        printf (“Not a valid ChemPath!!!\n”);
        chemPath->unref();
        return;
    }

    // Deselect everything and then select chemPath
    chemSelection->deselectAll();
    chemSelection->select(chemPath);
    chemPath->unref();
}

ChemSelection manages several lists of callback functions. Callback functions are functions within your application that you wish ChemSelection to invoke whenever a particular event occurs in the selection process. The types of callback-related events include the selection of a ChemPath, the deselection of the ChemPath, the start of a change to the selection list, the finish of a change to the selection list, the start of a lasso process, and the finish of a lasso process.

To add a callback function to a particular callback function list, use the appropriate add...Callback() method, such as addLassoStartCallback(). The functions on the callback list are invoked whenever a user presses down on the left mouse button to start using a lasso, drag rectangle, or selection sphere.

To remove a callback function from a particular callback function list, use the appropriate remove...Callback() function, such as removeLassoStartCallback().

Whenever callback-related events occur, ChemSelection looks at the callback function list associated with that event. If the list is not empty, every function on the list is invoked.

Of all the callback function lists, the one most commonly used is the one associated with the finish of all changes to the selection list. This list is managed with the addFinishCallback() and removeFinishCallback() methods. An example of adding a function to this list follows:

static void myFinishCB(void *, ChemSelection *cs);
...
chemSelection = new ChemSelection;
chemSelection->addFinishCallback(myFinishCB);

All of the methods that manage the callback function lists have the same argument and return type:

void ...Callback(ChemSelectionClassCB *f, void *userData = NULL)

For example,

void addChangeCallback(ChemSelectionClassCB *f, void *userData = NULL)

The following table describes these methods.