Merge pull request #11 from sphinxbio/add-selection-callback-doc

Add documentation about how to instantiate a selection callback

docs/selections.md

@@ -17,6 +17,38 @@ plugin.managers.camera.focusLoci(ligandLoci);
 plugin.managers.interactivity.lociSelects.select({ loci: ligandLoci });
 ```
 
+## Selection callbacks
+If you want to subscribe to selection events (e.g. to change external state in your application based on a user selection), you can use: `plugin.behaviors.interaction.click.subscribe`
+
+Here's an example of passing in a React "set" function to update selected residue positions.
+```typescript
+import {
+  Structure,
+  StructureProperties,
+} from "molstar/lib/mol-model/structure"
+// setSelected is assumed to be a "set" function returned by useState
+// (selected: any[]) => void
+plugin.behaviors.interaction.click.subscribe(
+  (event: InteractivityManager.ClickEvent) => {
+    const selections = Array.from(
+      plugin.managers.structure.selection.entries.values()
+    );
+    // This bit can be customized to record any piece information you want
+    const localSelected: any[] = [];
+    for (const { structure } of selections) {
+      if (!structure) continue;
+      Structure.eachAtomicHierarchyElement(structure, {
+        residue: (loc) => {
+          const position = StructureProperties.residue.label_seq_id(loc);
+          localSelected.push({ position });
+        },
+      });
+    }
+    setSelected(localSelected);
+  }
+)
+```
+
 ### `Molscript` language
 
 Molscript is a language for addressing crystallographic structures and is a part of the Mol* library found at `https://github.com/molstar/molstar/tree/master/src/mol-script`. It can be used against the Molstar plugin as a query language and traspiled against multiple external molecular visualization libraries(see [here](https://github.com/molstar/molstar/tree/master/src/mol-script/transpilers)).
@@ -76,4 +108,3 @@ var sel = Script.getStructureSelection(Q => Q.struct.generator.atomGroups({
 
 let loci = StructureSelection.toLociWithSourceUnits(sel);
 ```
-