Jmol JavaScript Object/Info

Callbacks

These callbacks, given in the Info variable, allow the page designer to get information about what is happening within the Jmol object. The name of a JavaScript function, wrapped in single- or double-quotes should be given as value. Do not use function() {....} syntax.

(In the former method, Jmol.js, these could be set using either jmolSetParameter() or jmolSetCallback() functions.)

As an alternative, the callbacks may also be defined from a script using the set command.

Example:

Info.pickCallback = "myPick";
function myPick() {
  alert('you clicked on atom with index=' + arguments[2]);
}

In each case, several parameters are returned and passed to the function (its arguments array):

1. the first parameter returned (argument zero) is always the Jmol Object name;
2. the 2nd and later parameters hold the information; not all are used by all callbacks (see below).

• animFrameCallback

Called: when a change in frame/model happens. When a file is loaded, the function is called once o twice before the loading starts (returning frame index zero) and once more after it finishes (returning frame index one).

arguments[1]: frame index (zero-based).

arguments[2]: file number (1-based).

arguments[3]: frame number within the file (1-based).

arguments[4-5]: first and last frame numbers within the current animation range (1-based added to one million).

arguments[6]: animation state: 0 (stopped) or 1 (animating)

arguments[7]: the value of animation direction: +1 or -1

arguments[8]: the current direction the animation is going: 1 (forward) or -1 (reverse)

arguments[9]: the name or title of the model, taken from the file contents (same that is displayed at the top of the window in the Jmol application)

arguments[10]: when a morph has been calculated, a floating point number corresponding to some intermediate value between two frames

• appletReadyCallback

Please, do not use this. Instead, use the readyFunction parameter described above.

• atomMovedCallback

Called: when the position of one or more atoms is modified; this usually requires set picking dragatom + mouse action, or rotateSelected or similar command.

arguments[1]: the affected atom set (as a Jmol atomset object - possibly in JSON construction; this will need parsing)

• echoCallback

Called: when Jmol produces some output from an echo command, or a show command (also if launched from the popup menu), or when a model is loaded (echoes the file header)...

arguments[1]: a text string with the output; it may include several lines

• evalCallback

(This is rather specialized and you will normally not need it).

If the Jmol javascript command is used (and is not forbidden by a setting of _jmol.noEval), this callback sends the JavaScript back to the web page for evaluation rather than initiating that evaluation within Jmol. For more details, see set EvalCallback

• hoverCallback

Called: when the mouse or pointer is positioned (hovers) over an atom.

arguments[1]: a text string with the current hover label (either the default or user-defined through set hoverLabel), followed by X, Y, Z coordinates of the atom.

Example for a MOL file: O14 #14 -0.438 -2.4279 -0.0068

Example for a PDB file: [ASN]46:A.ND2 #326 13.407 3.298 15.015

arguments[2]: the atom index (zero-based)

• loadStructCallback

Called: upon file loading (successful or not).

arguments[1]: the URL of the loaded file (full path+filename).

arguments[2]: the filename of the loaded file (without the path).

arguments[3]: the internal title of the model in the loaded file.

arguments[4]: any error messages generated.

arguments[5]: a numeric code: 3 when the file loaded successfully, 0 when the model was zapped, -1 when the loading failed.

arguments[6]: a text string with the frame number prior to loading the current model, in file.model syntax (for example, "3.1" or "1.1 - 3.31" if a whole range of models was framed).

arguments[7]: a text string with the last frame number after loading the current model, in file.model syntax.

Note: When multiple files are loaded with the same load command, only data for the last-loaded file is returned

• measureCallback

Called: after a measurement is started (double click on an atom) the callback runs while the measurement is in process: hovering over another atom, single-clicking or double-clicking on another atom

arguments[1]: a text string with data from the atoms involved in the measurement (from one up to 4); for each one of them, atom name (space) atom number. Starts and ends with square brackets and has a comma as delimiter. For example:

[H18 #18, O4 #4] for a distance (MOL file)

[H18 #18, O4 #4, H16 #16] for an angle (MOL file)

[[ILE]7:A.CD1 #47, [ASN]46:A.ND2 #326] for a distance (PDB file)

[[ILE]34:A.CD1 #245, [ILE]34:A.CG1 #243, [ILE]34:A.CB #242] for an angle (PDB file)

arguments[2]: during the measurement, the number of atoms involved so far; when measurement is finished, the index (zero-based) of this measurement in the list of measurements.

arguments[3]: during the measurement, the text string measurePending; when measurement is finished, measureCompleted

arguments[4]: the value of the measurement --angstroms or degrees--, either provisional or definitive.

• messageCallback

Called: every time Jmol issues some message (which will go to the scripting console).

You will need to parse the arguments output by this callback, searching for whatever text you are interested on detecting.

• minimizationCallback

Called: during a 3D structure optimization (energy minimization) initiated by the minimize command or the pop-up menu entry under calculation, at every reporting stage (usually every 10 steps). Also, extra calls at the beginning and end of the process.

arguments[1]: a text string declaring the status: either 'starting', 'running' or 'done'.

arguments[2]: a one-element array with sequential number of the reporting stage (0 for starting, repeat the last when done).

arguments[3]: a one-element array with the current value of energy (E).

arguments[4]: a one-element array with the current increment/decrement of energy between stages (dE).

arguments[5]: a text string indicating the kind of force field used (UFF or MMFF).

• pickCallback

Called: when the user clicks an atom -- or a bond (see below).

Note that for this to work, set atomPicking must be set true (it is by default).

Also, note that this description applies to the standard set picking ident; if another variety of picking has been issued, the output of the callback will be different.

• Clicking on an atom:

arguments[1]: a text string with atom id, atom number, and xyz coordinates in the form:

(MOL file) C6 #6 -0.307 -1.684 -0.717

(PDB file) [TYR]29:A.CE2 #210 -0.801 7.705 5.156

arguments[2]: an object with the single property valueOf(), whose result is the atom index (zero-based). Alternatively, the index as a JavaScript string may be obtained using "" + arguments[2].

arguments[3]: a null or empty object.

• Clicking on a bond:

If set bondPicking true has been issued, bonds will become clickable and also invoke the callback function, but the return from the function will be different:

arguments[1]: a text string in the form:

(MOL file) ["bond","3 1 C2 #2 -- C4 #4 1.361",-0.0,0.906,-0.306]

meaning bond number (indexed by order, 1-based), bond type (single, double...), 1st atom id, 1st atom number, 2nd atom id, 2nd atom number, bond length (distance), and xyz coordinates of the bond's midpoint.

(PDB file) ["bond","329 1 [ASN]46:A.N #319 -- [ALA]45:A.C #316 1.32",14.57,6.52,14.01]

arguments[2]: ?.

arguments[3]: an object with these properties:

model e.g. 1.1

index e.g. 328

type 'bond'

info a text string* with (space-delimited): bond number, bond type, 1st atom id, 1st atom number, --, 2nd atom id, 2nd atom number, bond length (*same as middle element of arguments[1] displayed above)

pt xyz coordinates of the bond's midpoint, e.g. {14.57, 6.52, 14.01}

modelIndex (e.g. 0 )

• resizeCallback

Called: when the JSmol object div size is changed. If the resizing is done with Jmol.resizeApplet(), the callback is immediate. When other methods are used for resizing (e.g. dragging the corner, changing CSS via Javascript...), this callback may be delayed until the JSmol panel is refreshed, e.g. by clicking on it.

arguments[1]: number of horizontal pixels (width) after the size change.

arguments[2]: number of vertical pixels (height).

• scriptCallback

Called: during execution of a Jmol script.

This will receive messages indicating the status of script execution. If it is not set, those messages go to the messageCallback instead.

• structureModifiedCallback

Called: each time the structure is modified (e.g. by the user in the ModelKit mode, or via some commands).

See set StructureModifiedCallback.

• syncCallback

Called: when the Jmol object issues/receives (?) a synchronization message to/from (?) another Jmol object (see the [https://chemapps.stolaf.edu/jmol/docs/#sync sync command).

Within this callback function the message is intercepted and may be accepted, modified or cancelled before being transmitted to the Jmol objects affected by synchronization.

Contributors

AngelHerraez