API Programming

This document provides some examples of how to get at the basic nuts and bolts of the API programming. The best source of examples is the OpenAstexViewer source code and the javadoc will describe all of the classes and methods.

With a reference to the MoleculeViewer, you need to get the MoleculeRenderer which actually manages the molecules.
```
MoleculeRenderer mr = moleculeViewer.getMoleculeRenderer();
```
The MoleculeRenderer gives you access to the molecules and their constituents.
```
int molCount = mr.getMoleculeCount()

for(int i = 0; i < molCount; i++){
    Molecule mol = mr.getMolecule(i);
}
```
Lets you get at the number and individual molecules.
When you have a molecule you can turn it on/off with mol.setDisplayed(0/1/2);

0 and 1 do what you would expect. 2 indicates toggle (if its on, turn it off and vice versa). When a molecule is off it is completely skipped in the renderering process. Any distance monitors should not be drawn to atoms in an off molecule.

If you just want to walk through the whole atom list for the MoleculeRenderer you can get an iterator, which will go through all molecules, chains, residues etc.

AtomIterator ai = mr.getAtomIterator();

while(ai.hasMoreElements()){
    Atom a = ai.getNextAtom();
}

getNextAtom() is a convenience method that calls getNextElement and casts it for you.

a.getElement() will give you the atomic number of the atom.

If you want to go through the molecular data structure long hand for some reason you can do it like this.

for(int m = 0; m < mr.getMoleculeCount(); m++){
  Molecule molecule = mr.getMolecule(m);

  for(int c = 0; c < molecule.getChainCount(); c++){
     Chain chain = molecule.getChain(c);

     for(int r = 0; r < chain.getResidueCount(); r++){
        Residue residue = chain.getResidue(r);
        int atomCount = residue.getAtomCount();

        for(int a = 0; a < atomCount; a++){
          Atom atom = residue.getAtom(a);
        }
     }
  }
}

Selecting atoms. When you have a reference to an atom just call setSelected(true/false). Selected atoms get the yellow dot when drawn. You can check if atoms are selected with isSelected();
If you want a list of all the atoms that are currently selected (you might have been using the user interface or building up a selection by some other means)
```
DynamicArray selectedAtoms = mr.getSelectedAtoms();
```
Then you can just go through these with
```
int count = selectedAtoms.size();

for(int i = 0; i < count; i++){
    Atom a = (Atom)selectedAtoms.get(i);
}
```
Display styles. This is usually all done through scriping language so there is no method call to do it (... obviously there should be).
So you get to do it directly. There is an attributes int in the atom. The render styles are (Atom.Displayed = lines, Atom.VDWSphere, Atom.Cylinder, Atom.BallAndStick) you just set them in the usual way
```
Atom a;
int style;

a.attributes |= style; // to turn on
a.attributes &= ~style; // to turn off
```
There are various other methods on atom that let you change the radii of all the display styles.
The renderer. If you want to create you own display objects you will need to use the actual low level renderer directly. This is referenced just as
```
Renderer r = mr.renderer;
```
Obviously there should be a method call for that. But more generally the way the MoleculeRenderer and the Renderer interact is not done quite right. This may well change in the near future.
On the renderer there are some methods for drawing different primitives. You should use the ones that take coordinates as double precision numbers. These are just world coordinates.
```
drawLine(double x1, double y1, double z1,
         double x2, double y2, double z2,
         int rgb1, int rgb2, int pixelWidth)

drawCylinder(double x1, double y1, double z1,
             double x2, double y2, double z2,
             int rgb1, int rgb2, double r)

drawSphere(double x, double y, double z, double r,
           int rgb, int transp)

drawString(double x, double y, double z,
           double zoff, int color, String string)
```
(zoff is an offset in the z-direction that is applied post transformation, so you can make things like labels always appear in front of a vdw sphere for example- see the scripting language for the string prefix notation that lets you control how the string is rendered.).
When you have changed anything through this API you must call moleculeRenderer.repaint(). This causes the MoleculeViewer to update itself, but also tells it that it actually needs to regenerate the picture. Otherwise it just copies what it had last time back to the Graphics object.
AstexViewer™ Copyright (C) 1999-2007 Astex Therapeutics Ltd.
OpenAstexViewer Copyright (C) 2007-2017 Mike Hartshorn