Jmol JavaScript Object/Functions - Revision history

AngelHerraez: some polishing and updated terminology

2025-08-20T15:46:21Z

some polishing and updated terminology

AngelHerraez: some polishing and updated terminology

2025-08-20T15:42:31Z

some polishing and updated terminology

AngelHerraez: some polishing and updated terminology

2025-08-20T11:51:19Z

some polishing and updated terminology

AngelHerraez: /* Functions that interact with a running JSmol object */

2025-08-19T18:28:23Z

‎Functions that interact with a running JSmol object

AngelHerraez: /* Functions that set CSS rules */

2025-08-19T18:02:34Z

‎Functions that set CSS rules

AngelHerraez: some polishing and updated terminology

2025-08-19T17:57:37Z

some polishing and updated terminology

AngelHerraez: some polishing and updated terminology

2025-08-19T17:16:32Z

some polishing and updated terminology

AngelHerraez: some polishing and updated terminology

2025-08-18T18:49:33Z

some polishing and updated terminology

Show changes

AngelHerraez: /* evaluateVar */

2023-04-05T10:41:51Z

‎evaluateVar

AngelHerraez: /* scriptWait */

2023-04-05T10:35:41Z

‎scriptWait

@@ Line 671: / Line 671: @@
 == Deprecated, unnecessary or not recommended ==
-The following methods are retained in Jmol-JSO since they were available in <code>Jmol.js</code>, but are not recommended. Most have simple scriptable alternatives.
+The following methods are retained in JSmol object since they were available in legacy <code>Jmol.js</code>, but are not recommended. Most have simple scriptable alternatives.
 === getInfo ===
@@ Line 690: / Line 690: @@
 === saveOrientation ===
-  Jmol.saveOrientation = function(JSmolObject, id)
+  Jmol.saveOrientation = function(JSmolObject, orientationID)
-Use instead <code>Jmol.script(myJmol, "save orientation " + id)</code>
+Use instead <code>Jmol.script(myJmol, "save orientation " + orientationID)</code>
 === restoreOrientation ===
-  Jmol.restoreOrientation = function(JSmolObject, id)
+  Jmol.restoreOrientation = function(JSmolObject, orientationID)
-Use instead <code>Jmol.script(myJmol, "restore orientation " + id)</code>
+Use instead <code>Jmol.script(myJmol, "restore orientation " + orientationID)</code>
 === restoreOrientationDelayed ===
-  Jmol.restoreOrientationDelayed = function(JSmolObject, id, delay)
+  Jmol.restoreOrientationDelayed = function(JSmolObject, orientationID, delayTime)
-Use instead <code>Jmol.script(myJmol, "restore orientation " + id + " " + delay)</code>
+Use instead <code>Jmol.script(myJmol, "restore orientation " + orientationID + " " + delayTime)</code>
 === scriptMessage ===

@@ Line 623: / Line 623: @@
 Runs a script synchronously, similarly to <code>scriptEcho()</code>, but returns a string including messages.
 Definition: <code>Jmol.scriptWait = function(JSmolObject, myScript)</code>
@@ Line 640: / Line 641: @@
 Example 2:
-  Jmol.scriptWait(myJmol, "backgroundred")
+  Jmol.scriptWait(myJmol, "backgroun red")
 does nothing --since the command is incorrect, note the typo-- and returns this in the JavaScript variable <code>x</code>:
@@ Line 647: / Line 648: @@
 ,scriptStatus,0,script ERROR: command expected
 ----
-         &gt;&gt; backgroundred &lt;&lt;
+         &gt;&gt; backgroun &lt;&lt;
 ,scriptStatus,0,Script completed
 ,scriptTerminated,1,Jmol script terminated successfully
 ,scriptTerminated,1,Jmol script terminated unsuccessfully: Jmol script terminated
-,scriptStarted,15,backgroundred
+,scriptStarted,15,backgroun red
 ,scriptError,0,Jmol script terminated
 </pre>
-'''NOTE: When using JSmol/Java do not call this method from a callback directly, as it may result in Java thread lock, causing the entire browser to hang.'''
+Always consider using <code>evaluateVar()</code> instead of <code>scriptWait()</code>. The syntax:
   x = Jmol.evaluateVar(myJmol, "script('background red; print backgroundColor')")
 will execute the script and additionally assign to the JavaScript variable <code>x</code> the string output by 'print', i.e. <code>[xff0000]</code>.
-If you still want to call Jmol.scriptWait from within a callback, use the following syntax to force the scriptWait call to be in a different thread:
+If you still want to call <tt>Jmol.scriptWait</tt> from within a callback, use the following syntax to force the scriptWait call to be in a different thread:
 <pre>
-function myCallback(app,param1,param2,....) {
+function myCallback(JSmolObject, param1, param2, ...) {
    setTimeout(function() {
      ...your JavaScript callback code here, including Jmol.scriptWait()...

@@ Line 497: / Line 497: @@
 All these functions must be applied to the unique '''<code>Jmol</code>''' constructor (this name is literal, cannot be changed) --see syntax and examples below.
-===evaluateVar===
+=== evaluateVar ===
 Allows to extract to JavaScript (e.g. to a variable) information from a variable set in the Jmol scripting language, a Jmol math expression, or some model information.
-Definition: <code>Jmol.evaluateVar = function(applet, molecularMath)</code>
+Definition: <code>Jmol.evaluateVar = function(JSmolObject, molecularMath)</code>
 Examples:
@@ Line 519: / Line 519: @@
 Note: An older version of this method, <code>Jmol.evaluate()</code>, is deprecated, as it only returns String, Integer, or Float values.
-===getPropertyAsArray===
+=== getPropertyAsArray ===
 Returns information of the JSmol object, in the form of a JavaScript array, when applicable, or other appropriate JavaScript variable type such as boolean, number, or string.
-Definition: <code>Jmol.getPropertyAsArray = function(JSmolObject,sKey,sValue)</code>
+See the [{{ScriptingDoc}}#getproperty Scripting Documentation] for a list of the available properties.
 Example:
@@ Line 535: / Line 537: @@
   var myInfo = myFirstAtom.info; // value of the 'info' prroperty of the JavaScript object 'myFirstAtom'
-===getPropertyAsJavaObject===
+=== getPropertyAsJavaObject ===
 Returns the property as a Java (not JavaScript) object. This function is for advanced users only and is not generally recommended, as it delivers a pointer to the Java object itself, not a copy of it. This pointer may or may not be valid indefinitely and may or may not be properly garbage-collected by all browsers. The principal use of this function is for access to public Viewer methods that are not generally available via the JSmol Object interface.
@@ Line 541: / Line 543: @@
 Note that the HTML5 version of JSmol returns objects that for all practical purposes are "Java Objects" using this method. The only difference is that the JavaScript implementations have no aspect of "private" or "public" -- all methods are effectively public.
-Definition:  <code>Jmol.getPropertyAsJavaObject = function(JSmolObject,sKey,sValue)</code>
+Definition:  <code>Jmol.getPropertyAsJavaObject = function(JSmolObject, sKey, sValue)</code>
 Example:
@@ Line 549: / Line 551: @@
 Many of these public methods are listed in [{{SVN Trunk}}Jmol/src/org/jmol/api/JmolViewer.java JmolViewer.java]
-===getPropertyAsJSON===
+=== getPropertyAsJSON ===
-Returns data as per jmolGetPropertyAsArray, but always as a JavaScript '''string''' in JavaScript Object Notation. This string can then be surrounded by parentheses and evaluated to create '''array''' content. Alternatively, if may be converted to a JavaScript '''object''' with properties, as described below.
+Returns data as per <tt>jmolGetPropertyAsArray</tt>, but always as a JavaScript '''string''' in JavaScript Object Notation. This string can then be surrounded by parentheses and evaluated to create '''array''' content. Alternatively, if may be converted to a JavaScript '''object''' with properties, as described below.
-Definition:  <code>Jmol.getPropertyAsJSON = function(JSmolObject,sKey,sValue)</code>
+Definition:  <code>Jmol.getPropertyAsJSON = function(JSmolObject, sKey, sValue)</code>
 Example:
-  var z = Jmol.getPropertyAsJSON(myJmol, "filename") // {"filename": "file:/C:/data/caffeine.xyz"}
+  var a = Jmol.getPropertyAsJSON(myJmol, "filename")
 Examples:
-  var z = Jmol.getPropertyAsJSON(myJmol, "filename");
+  var a = Jmol.getPropertyAsJSON(myJmol, "filename");
-  alert(  JSON.parse(z).filename ); // the url of the model file
+  alert( JSON.parse(a).filename ); // the url of the model file
-  var z = Jmol.getPropertyAsJSON(myJmol, "appletInfo");
+  var b = Jmol.getPropertyAsJSON(myJmol, "appletInfo");
-  var d = JSON.parse(z);
+  var c = JSON.parse(b);
-  alert( d.appletInfo.version ); // e.g. 14.6.2_2016.08.28
+  alert( c.appletInfo.version ); // e.g. 14.6.2_2016.08.28
-  alert( d.appletInfo.htmlName ); // the name of the JSmol object
+  alert( c.appletInfo.htmlName ); // the name of the JSmol object; in this case, "myJmol"
-  alert( d.appletInfo.documentBase ); // the url of the page containing the JSmol object
+  alert( c.appletInfo.documentBase ); // the url of the page containing the JSmol object
-===getPropertyAsString===
+=== getPropertyAsString ===
 Returns data as per jmolGetPropertyAsArray, but always as a JavaScript string. In the case of arrayed data, this string is formatted for easier reading (as in example #3 below).
-Definition:  <code>Jmol.getPropertyAsString = function(JSmolObject,sKey,sValue)</code>
+Definition:  <code>Jmol.getPropertyAsString = function(JSmolObject, sKey, sValue)</code>
 Examples:
   var s = Jmol.getPropertyAsString(myJmol, 'stateInfo');
-−
   img.src = 'data:image/jpeg;base64,' + Jmol.getPropertyAsString(myJmol, 'image');
-−
   var f = Jmol.getPropertyAsString(myJmol, 'fileName');
   // returns (newline)fileName(tab)"<nowiki>https://files.rcsb.org/download/1hho.pdb</nowiki>"
@@ Line 596: / Line 601: @@
 ===  script ===
-Runs a Jmol script asynchronously, meaning the script is put into a queue and most likely not processed before the function call is returned. This call can be made any time after applet creation; one does not have to wait until the applet is ready for receiving scripts (as was the case with Jmol/Java when Jmol.js was used).
+Runs a Jmol script asynchronously, meaning the script is put into a queue and most likely is not processed before the function call is returned. This call can be made any time after creation of the JSmol object; one does not have to wait until JSmol is ready for receiving scripts (as was the case with Jmol/Java when Jmol.js was used).
 Definition: <code>Jmol.script = function(JSmolObject, myScript)</code>
@@ Line 608: / Line 613: @@
 === scriptEcho ===
-Runs a script synchronously, returning the text that might have gone to the console. '''NOTE: When using JSmol/Java do not call this method from a callback directly, as it may result in Java thread lock, causing the entire browser to hang.''' See alternatives under <code>scriptWait</code>.
+Runs a script synchronously, returning the text that might have gone to the console. See alternatives under <code>scriptWait</code>.
 Definition: <code>Jmol.scriptEcho = function(JSmolObject, myScript)</code>

@@ Line 521: / Line 521: @@
 ===getPropertyAsArray===
-Returns applet information in the form of a JavaScript array, when applicable, or other appropriate JavaScript variable type such as boolean, number, or string.
+Returns information of the JSmol object, in the form of a JavaScript array, when applicable, or other appropriate JavaScript variable type such as boolean, number, or string.
 Definition: <code>Jmol.getPropertyAsArray = function(JSmolObject,sKey,sValue)</code>
-Examples:
+Example:
-  var atoms = Jmol.getPropertyAsArray(myJmol, "atomInfo", "all");
+  var myAtoms = Jmol.getPropertyAsArray(myJmol, "atomInfo", "all"); // a variable of array type
-  var atom1 = atoms[0];
+  var myFirstAtom = myAtoms[0]; // first item of the JavaScript array 'myAtoms'; a variable of object type
-  var x = atom1.x;
-  var info = atom1.info;
+Then, to obtain the X coordinate of the first atom in the structure (like 3.294):
 ===getPropertyAsJavaObject===
-Returns the property as a Java (not JavaScript) object. This function is for advanced users only and is not generally recommended, as it delivers a pointer to the Java object itself, not a copy of it. This pointer may or may not be valid indefinitely and may or may not be properly garbage-collected by all browsers. The principal use of this function is for access to public Viewer methods that are not generally available via the applet interface.
+Returns the property as a Java (not JavaScript) object. This function is for advanced users only and is not generally recommended, as it delivers a pointer to the Java object itself, not a copy of it. This pointer may or may not be valid indefinitely and may or may not be properly garbage-collected by all browsers. The principal use of this function is for access to public Viewer methods that are not generally available via the JSmol Object interface.
-Note that even the HTML5 version of JSmol returns objects that for all practical purposes are "Java Objects" using this method. The only difference is that the JavaScript implementations have no aspect of "private" or "public" -- all methods are effectively public.
+Note that the HTML5 version of JSmol returns objects that for all practical purposes are "Java Objects" using this method. The only difference is that the JavaScript implementations have no aspect of "private" or "public" -- all methods are effectively public.
 Definition:  <code>Jmol.getPropertyAsJavaObject = function(JSmolObject,sKey,sValue)</code>
 Example:
-  var viewer = Jmol.getPropertyAsJavaObject(myJmol, "jmolViewer")
+  var myViewer = Jmol.getPropertyAsJavaObject(myJmol, "jmolViewer")
-  var radius = viewer.getRotationRadius()
+  var myRadius = viewer.getRotationRadius()
 Many of these public methods are listed in [{{SVN Trunk}}Jmol/src/org/jmol/api/JmolViewer.java JmolViewer.java]

@@ Line 475: / Line 475: @@
 === setAppletCss ===
 Definition: <code>Jmol.setAppletCss = function(cssClass, text)</code>
 === setButtonCss ===

@@ Line 251: / Line 251: @@
 == Functions for creating controls ==
-These Jmol functions create elements of the page that the page visitor can use to interact with the
+These Jmol functions create elements of the page that the page visitor can use to interact with the JSmol object. Again, all these functions must be applied to the unique '''<code>Jmol</code>''' constructor (this name is literal, cannot be changed) --see syntax and examples below.
 The first parameter for nearly all of these functions, <tt>JSmolObject</tt>, must be a reference to the object that will receive action of the control. Such reference is either the JSO object itself or its name-id (e.g. "myJmol" in the examples above).
@@ Line 272: / Line 271: @@
   };
   Jmol.getApplet("myJmol", myInfo);
-  Jmol.jmolButton(myJmol,"spacefill on", "display as vdW spheres");
+  Jmol.jmolButton(myJmol,"spacefill on", "display as VdW spheres");
-<tt>script</tt> is run when the button is pressed.
+<tt>script</tt> will be run when the button is pressed.
 As a special syntax (valid for any other controls as well as the button described here), instead of a Jmol script you can run a JavaScript function that you have defined, by providing this in place of the script: <code>[funcName, param1, param2, param3...]</code>
 The function must be defined in this way:
@@ Line 288: / Line 287: @@
 <tt>label</tt> is the text in the button; if not specified, it defaults to the first 32 characters of the script.
-<tt>id</tt> (optional) will be set as both the HTML id and HTML name. It will default to jmolButton0, jmolButton1, etc.
+<tt>id</tt> (optional) will be set as both the HTML id and HTML name of the button. It will default to jmolButton0, jmolButton1, etc.
 :''Advanced:''
@@ Line 332: / Line 331: @@
 === jmolCommandInput ===
 Definition: <code>Jmol.jmolCommandInput(JSmolObject<em style="color:peru;">, label, size, id, title</em>)</code>
 === jmolLink ===
@@ Line 351: / Line 362: @@
 === jmolMenu ===
 Definition: <code>Jmol.jmolMenu(JSmolObject, arrayOfMenuItems<em style="color:peru;">, size, id, title</em>)</code>
 === jmolRadio ===

@@ Line 189: / Line 189: @@
 Definition: <code>Jmol.setGrabberOptions = function(options)</code>
-Allows to customize the items offered in the drop-down menu that fetches molecules from databases, when using <code>addSelectionOptions:true</code>. Example:
+When <code>addSelectionOptions:true</code> is used (in the <code>Info</code> variable), a drop-down menu is displayed below the JSmol panel.
   Jmol.setGrabberOptions([
     ["$", "small molecules at NCI"],
     [":", "small molecules at PubChem"],
-    ["==", "ligands at PDB"],
+    ["==", "ligands at RCSB PDB"],
-    ["=", "macromolecules at PDB"]
+    ["=", "macromolecules at RCSB PDB"]
-  ])
+  ]);
-The first value in each element is the JmolScript prefix to direct the request to the database (this cannot be customized). The second value is the text that is displayed in the drop-down menu in the page, below the JSmol object.
+The first value in each element is the JmolScript prefix to direct the request to the database (see [[Database Connection]] for the available prefixes). The second value is the text displayed in the drop-down menu option.
 === showInfo ===
@@ Line 203: / Line 206: @@
 Definition: <code>Jmol.showInfo = function(JSmolObject, tf)</code>
-This displays or hides the information panel (which holds the log console, or maybe an associated JME applet). By default, that panel is located in the same position as the Jmol viewer, so displaying Info will hide Jmol and vice versa.
+The <tt>tf</tt> parameter is a true or false flag.
-The <tt>tf</tt> parameter is a true or false flag.
+This displays or hides the information panel (which holds the log console, or maybe a JSME panel linked to JSmol). By default, that panel is located in the same position as the JSmol viewer, so displaying Info will hide JSmol and vice versa.
 === setInfo ===
-Definition: <code>Jmol.setInfo = function(JSmolObject, info, isShown)</code>
+Definition: <code>Jmol.setInfo = function(JSmolObject, infoDiv, isShown)</code>
-Sets the information div for the JSmol object to be ''info'' (HTML) and optionally displays it.
+Sets the information panel for the JSmol object to be located in <nowiki><div id="infoDiv"></div></nowiki> (HTML, DOM node) and optionally displays it.
 === setXHTML ===
 Definition: <code>Jmol.setXHTML = function(id)</code>
-Indicates id of the DOM node into which the JSmol object will be inserted, following XHTML format when creating page elements. Largely untested.
+''Largely untested.'' Indicates the ''id'' of the DOM node into which the JSmol object will be inserted, following XHTML format when creating page elements.
 Example:
 <pre>
-<!doctype html>
+<!doctype HTML>
 <head>
 <meta charset="UTF-8" />
-<title>test XHTML</title>
+<title>Test JSmol in XHTML</title>
 <script type="text/javascript" src="JSmol.min.js"></script>
 <script type="text/javascript">

@@ Line 449: / Line 449: @@
 ===evaluateVar===
-Allows to extract to JavaScript (e.g. to a variable) information from a variable set in the Jmol scripting language, a Jmol math expression, or some model information. Examples:
+Allows to extract to JavaScript (e.g. to a variable) information from a variable set in the Jmol scripting language, a Jmol math expression, or some model information.
-Definition: <code>Jmol.evaluateVar = function(applet,molecularMath)</code>
+Definition: <code>Jmol.evaluateVar = function(applet, molecularMath)</code>
 Examples:
-  alert( Jmol.evaluateVar(myJmol, "a") );
+  x = Jmol.evaluateVar(myJmol, "a");
-   // Displays the value of the 'a' variable if set in JmolScript.
+   // JavaScript variable <code>x</code> receives the value of the 'a' variable if it was previously set in JmolScript.
-  alert( Jmol.evaluateVar(myJmol, "{*}.xyz") );
+  x = Jmol.evaluateVar(myJmol, "{*}.xyz");
-   // Displays the coordinates of the geometric center of the model.
+   // JavaScript variable <code>x</code> receives the coordinates of the geometric center of the model.
-  alert( Jmol.evaluateVar(myJmol, "{*}.length") );
+  x = Jmol.evaluateVar(myJmol, "{*}.length");
-   // Displays the total number of atoms in the model.
+   // JavaScript variable <code>x</code> receives the total number of atoms in the model.
-  alert( Jmol.evaluateVar(myJmol, "{carbon}.bonds.length.min") );
+  x = Jmol.evaluateVar(myJmol, "{carbon}.bonds.length.min");
-   // Displays the minimum bond length between carbon atoms.
+   // JavaScript variable <code>x</code> receives the minimum bond length between carbon atoms.
-  alert( Jmol.evaluateVar(myJmol, "_atomPicked") );
+  x = Jmol.evaluateVar(myJmol, "_atomPicked");
-   // Displays the index of the atom that was most recently picked.
+   // JavaScript variable <code>x</code> receives the index of the atom that was most recently picked.
 Note: An older version of this method, <code>Jmol.evaluate()</code>, is deprecated, as it only returns String, Integer, or Float values.