View source for Jmol JavaScript Object/Functions

= Functions for Jmol JavaScript Object =

Parent page: [[Jmol JavaScript Object]].

__TOC__

== Functions for creation or display of Jmol Objects ==

The following functions all relate to applet creation or display. All of them must be applied to the unique '''<code>Jmol</code>''' constructor (this name is literal, cannot be changed) --see syntax and examples below.

=== getApplet === 
Definition: <code>Jmol.getApplet = function(id, Info, checkOnly)</code>

This function creates in JavaScript space of the webpage the Jmol object (either a Jmol/Java applet or a JSmol object). For example:
 Jmol.getApplet("myJmol", Info);

The above example will create a <tt>myJmol</tt> variable that holds the Jmol Object, and the object will be inserted in the page (unless <code>Jmol.setDocument()</code> has been set false, see below).

<tt>checkOnly</tt> is an optional true/false flag that allows, when set <code>true</code>, to get a JavaScript Object that can be checked to see what type of Jmol Object ''would'' be created on this particular platform -- a signed Java applet, an unsigned Java applet, a JSmol canvas, an image, a WebGL canvas, etc.

=== getTMApplet === 

This function creates and inserts the [[Lightweight_JSmol|lightweight variety]] of JSmol object.

=== getAppletHtml === 

Definition:  <code>Jmol.getAppletHtml = function(JmolObject)</code>

or: <code>Jmol.getAppletHtml = function(id, Info)</code>

Useful for inserting the Jmol object code into the page, either after page has loaded or in the case when the object was generated and stored in a variable, e.g. after <code>Jmol.setDocument(0)</code>. It is particularly useful with <code>.innerHTML</code> inside <code>window.onload</code> or in a function fired by user action  (or the jQuery equivalents <code>.html()</code> and <code>$(document).ready</code>). Some examples:

'''(1)''' Recommended, simplest syntax that creates 2 objects and inserts them at the same time:
<pre>
$(document).ready(function(){
  $("#place1").html(Jmol.getAppletHtml("jmol1", Info));
  $("#place2").html(Jmol.getAppletHtml("jmol2", Info));
});
</pre>
'''(2)''' The following is equivalent (using html syntax instead of jQuery syntax). Note, however, that in some complex pages this may fail to insert the JSmol object.
<pre>
window.onload = function(){
  document.getElementById("place1").innerHTML = Jmol.getAppletHtml("jmol1", Info);
  document.getElementById("place2").innerHTML = Jmol.getAppletHtml("jmol2", Info);
});
</pre>

'''(3)''' If you need to create the Jmol Objects first, and insert them later on:

Using jQuery syntax:
<pre>
$(document).ready(function(){
  Jmol.setDocument(0);
  Jmol.getApplet("jmol1", Info); // creates the object but does not insert it
  Jmol.getApplet("jmol2", Info);
  [...] // other actions, that may affect the Jmol objects
  // now, let's insert the objects in the page:
  $("#place1").html(Jmol.getAppletHtml(jmol1));
  $("#place2").html(Jmol.getAppletHtml(jmol2));
});
</pre>
'''(4)''' Using html syntax:
<pre>
window.onload = function(){
  Jmol.setDocument(0);
  Jmol.getApplet("jmol1", Info); // creates the object but does not insert it
  Jmol.getApplet("jmol2", Info);
  [...] // other actions, that may affect the Jmol objects
  // now, let's insert the objects in the page:
  document.getElementById("place1").innerHTML = Jmol.getAppletHtml(jmol1);
  document.getElementById("place2").innerHTML = Jmol.getAppletHtml(jmol2);
});
</pre>

'''(5)''' The same approaches may be followed to insert the Jmol Object upon user action, rather than upon page load:
<pre>
function insertMyJmol(){
  $("#myJmolContainer").html(Jmol.getAppletHtml("myJmol", Info));
});

<div id="myJmolContainer"></div>
<input type="button" value="show 3D structure" onClick="insertMyJmol()">
</pre>

<pre>
function insertMyJmol2(targetDiv, objectID){
  $("#"+targetDiv).html(Jmol.getAppletHtml(objectID, Info));
});

<div id="myPlace"></div>
<input type="button" value="show 3D structure" onClick="insertMyJmol2('myPlace','myJmol')">
</pre>

See also under [[#Jmol.setDocument|Jmol.setDocument()]]

=== getVersion === 

Definition: <code>Jmol.getVersion = function()</code>

This function returns the version of Jmol-JSO, like <code>Jmol-JSO 13.1.12</code>.

Example:
<pre>
var t = Jmol.getVersion(myJmol);
alert(t);
</pre>

=== resizeApplet === 

Definition: <code>Jmol.resizeApplet = function(JmolObject,size)</code>

Used to change the dimensions of the specified Jmol object.
					
<tt>size</tt>: a value or a pair of width/height values in an array, either expressed in pixels or as percent.

Examples:
<pre>
Jmol.resizeApplet(myJmol, 400);
Jmol.resizeApplet(myJmol, [400,700]);
Jmol.resizeApplet(myJmol, "100%");
Jmol.resizeApplet(myJmol, ["50%","60%"]);
</pre>

Alternative method: you can create an envelope <code>div</code> that encloses the point of insertion of the Jmol object, declare the size of the latter as 100% in the <code>Info</code> variable, and control via CSS and JavaScript the initial and changed size of the envelope <code>div</code>. This method also supports user-resizable envelopes (e.g. jQueryUI's <code>resizable</code>); Jmol will resize accordingly in real time.

=== setAppletSync === 

Definition: <code>Jmol.setAppletSync = function(JmolObjects, commands, isJmolJSV)</code>

=== setDocument === 

Definition: <code>Jmol.setDocument = function(doc)</code>

<tt>doc</tt> is the target html context where the Jmol Object must be created.

If using <code>Jmol.setDocument(false)</code> or <code>Jmol.setDocument(0)</code>, 
the Jmol Object may be later inserted using <code>Jmol.getAppletHtml()</code>.
What happens is that the HTML code for the object is
put into the internal <code>applet._code</code> variable and not written to the page.
Then you can still refer to the applet, but place it on the page after the controls are made,
or inject ot into the page upon some user action. 

Example:
<pre>
Jmol.setDocument(false);
Jmol.getApplet("myJmol", Info);
(...)
document.getElementById('someContainer').innerHTML = Jmol.getAppletHtml(myJmol);
</pre>
or, using jQuery syntax;
<pre>
Jmol.setDocument(false);
Jmol.getApplet("myJmol", Info);
(...)
$("#someContainer").html(Jmol.getAppletHtml(myJmol));
</pre>

For some situations this may be equivalent to a simpler alternative: 
Just define the Jmol object variable like <code>var myJmol = "myJmol"</code> and then, 
"myJmol" will suffice when providing any options or creating buttons and controls.
Finally, use <code>Jmol.getApplet(myJmol,....)</code> and the Object will work.

=== setGrabberOptions === 
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:
 Jmol.setGrabberOptions([
   ["$", "small molecules at NCI"],
   [":", "small molecules at PubChem"],
   ["==", "ligands at PDB"],
   ["=", "macromolecules at 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 Jmol object.

=== showInfo === 

Definition: <code>Jmol.showInfo = function(JmolObject, 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.

=== setInfo === 	

Definition: <code>Jmol.setInfo = function(JmolObject, info, isShown)</code>

Sets the information div for the Jmol object to be ''info'' (HTML) and optionally displays it.

=== setXHTML ===
Definition: <code>Jmol.setXHTML = function(id)</code>

Indicates id of the DOM node into which the Jmol object will be inserted, following XHTML format when creating page elements. Largely untested.

Example:
<pre>
<!doctype html>
<head>
<meta charset="UTF-8" />
<title>test XHTML</title>
<script type="text/javascript" src="JSmol.min.js"></script>
<script type="text/javascript">
$(document).ready(function(){
  var Info = {
    height: 300,
    width: 300,
    j2sPath: "j2s",
    use: "HTML5"
  };
  Jmol.setXHTML('myContainer');
  Jmol.getApplet(myJmol, Info);
});
</script>
</head>
<body>
<p>Some text</p>
<div id="myContainer"></div>
<p>Some more text</p>
</body>
</html>
</pre>

== Functions for creating controls ==

These Jmol functions create elements of the page that the page visitor can use to interact with the
applet or applet surrogate. 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>JmolObject</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).

:In the following descriptions, a <em style="color:peru;">colored italic font</em> is used for parameters that are optional.  

=== jmolButton === 

Inserts in the page a button with a text content.

Definition: <code>Jmol.jmolButton(JmolObject, script<em style="color:peru;">, label, id, title</em>)</code>

Example:
 var myInfo = {
   color: "#DDDDFF",
   script: "load myMolecule.mol;",
   height: 300,
   width: 300
 };
 Jmol.getApplet("myJmol", myInfo);
 Jmol.jmolButton(myJmol,"spacefill on", "display as vdW spheres");

<tt>script</tt> is 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:
 function funcName(btn, obj, target) {
     // Entire array object is provided as 2nd argument.
     var param1 = obj[1];
     var param2 = obj[2];
     var param3 = obj[3];
     // JavaScript to execute here.
     ....
 }

<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.

:''Advanced:''
:In addition, the button will be included in a <code><nowiki><span></nowiki></code> element that will have an HTML id of "span_" plus the given <tt>id</tt>, and an HTML title of the given <code>title</code>.
:Browsers will hence show <tt>title</tt> as a tooltip when mouse pointer stays over the button. 

=== jmolCheckbox === 
Definition: <code>Jmol.jmolCheckbox(JmolObject, scriptWhenChecked, scriptWhenUnchecked, labelHtml<em style="color:peru;">, isChecked, id, title</em>)</code>

Inserts a checkbox into the page, followed immediately by <tt>labelHtml</tt>. 

<tt>scriptWhenChecked</tt> is run when the checkbox is checked by the user.

<tt>scriptWhenUnchecked</tt> is run when the user unchecks the checkbox. 

<tt>isChecked</tt> should be set to a non-false value (e.g.: <tt>true</tt>) if you want the checkbox to be checked or marked upon page loading (default: unchecked). 

<tt>id</tt> will be set as both the HTML id and HTML name. It will default to jmolCheckbox0, jmolCheckbox1, etc. 

Browsers will show <tt>title</tt> as a tooltip when mouse pointer stays over the checkbox or over its accompanying <tt>labelHtml</tt>. 

Example:
 Jmol.jmolCheckbox(myJmol,"spacefill on","spacefill off","toggle display as spheres");

=== setCheckboxGroup ===
Definition: <code>Jmol.setCheckboxGroup(chkMaster,chkBoxes)</code>

Starting with previously inserted checkboxes (using <code>Jmol.jmolCheckbox()</code>), this allows to establish a relation between one "parent" or "leader" checkbox and one or more "child" or "follower" checkboxes, according to these rules: 
* Whenever the leader is checked, all its followers get automatically checked.
* Whenever the leader is unchecked, all its followers get automatically unchecked.
* Whenever one of the followers is checked or unchecked, its siblings are examined; if all have the same state, the leader will be checked or unchecked accordingly. If they have mixed states, the leader would have a "partially checked" state, which is currently not implemented visually ([[Jmol_JavaScript_Object/Functions/CheckboxGroup#Partially selected checkbox|read more]]).

The Jmol scripts associated to each checkbox when it was inserted/defined will be executed when its state changes due to action on another checkbox.

<tt>chkMaster</tt>  is the ID given to the checkbox that will act as leader. This ID may have been specified in its <code>Jmol.jmolCheckbox()</code>) definition, or may be a number (if ID was not specified, sequential numeric IDs are assigned by default, starting from zero). 

<tt>chkBoxes</tt> is an array of one or more IDs or numbers, pointing to the checkboxes that will act as followers. Alternatively, it can be a comma-delimited list of text strings (the IDs).

See [[Jmol_JavaScript_Object/Functions/CheckboxGroup|examples]].

Any number of groups can be set in a page, with any number of component checkboxes. Nesting groups within other groups is also possible (i.e., a follower in one group may be the leader for an inner group).

=== jmolCommandInput === 
Definition: <code>Jmol.jmolCommandInput(JmolObject<em style="color:peru;">, label, size, id, title</em>)</code>

=== jmolLink === 
Definition: <code>Jmol.jmolLink(JmolObject, script<em style="color:peru;">, text, id, title</em>)</code>

<tt>script</tt> is run when the user clicks on the link.

<tt>text</tt> is written to the page as a link. If it is not specified, it defaults to the first 32 characters of <tt>script</tt>.

<tt>id</tt> will be set as both the HTML id and HTML name. It will default to jmolLink0, jmolLink1, etc.

Example:
 Jmol.jmolLink(myJmol,"load adenine.mol","adenine");

:''Advanced:''
:In addition, the link text will be included in a <code><nowiki><span></nowiki></code> element that will have an HTML id of "span_" plus the given <tt>id</tt>, and an HTML title of the given <tt>title</tt>.
:Browsers will hence show <tt>title</tt> as a tooltip when mouse pointer stays over the link. 

=== jmolMenu === 
Definition: <code>Jmol.jmolMenu(JmolObject, arrayOfMenuItems<em style="color:peru;">, size, id, title</em>)</code>

=== jmolRadio === 
Definition: <code>Jmol.jmolRadio(JmolObject, script<em style="color:peru;">, labelHtml, isChecked, separatorHtml, groupName, id, title</em>)</code>

Inserts a single radio button into the page, followed immediately by <tt>labelHtml</tt>.  

<tt>script</tt> is run when the user checks the radio button.

<tt>labelHtml</tt> is written to the page right after the radio button. Note that it '''must''' be a text string (if you wanted to use a number, wrap it in quotes). 

<tt>isChecked</tt> should be set to a non-false value (e.g.: <tt>true</tt>) if you want the radio button to be  marked upon page loading (default: not checked). 

Radio buttons will be assigned to the group specified by <tt>groupName</tt>. In other words, linked radio buttons (those mutually exclusive in their checked state) will be those that share the same value of <tt>groupName</tt>. If you don't want to use a groupName, all buttons will be assigned to the same group (with an automatically assigned name).

<tt>separatorHtml</tt> is used to specify HTML code that should be placed after the radio button and its <tt>labelHtml</tt>. For example, to put the radio buttons on separate lines you should pass in <tt><nowiki><br></nowiki></tt> as the actual parameter. If <tt>separatorHtml</tt> is not specified, it defaults to a non-breaking space. 

<tt>id</tt> will be set as the HTML id. If not provided, a default name is made up automatically.

The radio button label will be surrounded by <tt><nowiki><label></nowiki></tt> tags; the effect is that clicking on the label text will have the same effect as clicking on the radio button itself. 

Example:
 Jmol.jmolRadio(myJmol,"spacefill 23%; wireframe 0.15;","ball and stick",true);

=== jmolRadioGroup === 
Definition: <code>Jmol.jmolRadioGroup(JmolObject, arrayOfRadioButtons<em style="color:peru;">, separatorHtml, groupName, id, title</em>)</code>

Inserts a group of mutually-exclusive radio buttons into the page.  

<tt>arrayOfRadioButtons</tt> is usually specified using the JavaScript square brackets [ entryA, entryB, ... ] notation. Each entry is generally another array which contains a script, a label (text displayed in the page after the radio button), and an optional isChecked flag. If an entry is a single string instead of an array, then that string is used for both the script and the label. 

<tt>separatorHtml</tt> is used to specify HTML code that should be placed after each radio button and its label, but before the next radio button. For example, to put the radio buttons on separate lines you should pass in <tt><nowiki><br></nowiki></tt> as the actual parameter. If <tt>separatorHtml</tt> is not specified, it defaults to a non-breaking space. 

Radio buttons will all belong to a group with an HTML name of <tt>groupName</tt>. If you don't specify one, it will be automatically made up.

The whole group of radio buttons will be included in a <tt><nowiki><span></nowiki></tt> element that will have as its HTML id the value of <tt>id</tt> or, if this is not given, the value of <tt>groupName</tt>.
* In turn, each radio button + label will be surrounded by a <tt><nowiki><span></nowiki></tt> element with an HTML id <tt>span_</tt> plus the group's <tt>id</tt> plus an underscore plus a sequential number (starting at zero), and as its HTML title, the common <tt>title</tt>.
* Each radio button will have as its HTML id the group's <tt>id</tt> plus an underscore plus a sequential number (starting at zero).
* Each radio button label will be surrounded by <tt><nowiki><label></nowiki></tt> tags; the effect is that clicking on the label text will have the same effect as clicking on the radio button itself. 

Example:
<pre> var r = [
    ["spacefill 23%; wireframe 0.15;","ball and stick",true],
    ["spacefill off; wireframe 0.15;","sticks"],
    ["spacefill on; wireframe off;","spheres"]
 ];
 Jmol.jmolRadioGroup(myJmol, r, "<br>", "atomstyle");
</pre>

== Functions that insert HTML ==

These simple commands just deliver HTML to the page. They are merely convenience functions for use 
from within the <code>body</code> so as not to have to continually switch in and out of script tags. 

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.

:Much better practice is to do all control creation in the header of the page, from within jQuery's <code>$(document).ready()</code> function, using <code>Jmol.setDocument(0)</code>, appending the HTML to a growing string using the control-specific functions, then setting the code in a predefined <code>div</code> element using the jQuery <code>$('#divId').html()</code> function.

=== jmolBr === 
Inserts a soft line break. Its only use is:
 Jmol.jmolBr()

=== jmolHtml === 
Allows to insert in the page any HTML code you may wish. Example:
 <nowiki>Jmol.jmolHtml(' <b style="color:red">H<sub>2</sub>O</b> ')</nowiki>

== Functions that set CSS rules ==

These functions, called prior to the creation of the associated object(s), allow the page designer
to add specific attributes (usually, but not necessarily CSS style attributes) to the HTML tag(s) that
will be created later. This allows setting one or more common style attributes for, for example, all 
buttons in a certain cell of a table, or all radio buttons of a certain group. Either a class name or an attribute can be given. For example:
<pre>
  Jmol.setButtonCss("wideBtn");

  <style type="text/css">
  .wideBtn { width:220px; }
  </style>
</pre>
<pre>
  Jmol.setButtonCss(null, "style='width:160px'");
</pre>

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.

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

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

=== setCheckboxCss === 
Definition: <code>Jmol.setCheckboxCss = function(cssClass, text) </code>

=== setLinkCss === 
Definition: <code>Jmol.setLinkCss = function(cssClass, text) </code>

=== setMenuCss === 
Definition: <code>Jmol.setMenuCss = function(cssClass, text)</code>

=== setRadioCss ===
Definition: <code>Jmol.setRadioCss = function(cssClass, text)</code>

== Functions that interact with a running Jmol Object ==

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===

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:

Definition: <code>Jmol.evaluateVar = function(applet,molecularMath)</code> 

Examples:
 alert( Jmol.evaluateVar(myJmol, "a") );
  // Displays the value of the 'a' variable if set in JmolScript.
 alert( Jmol.evaluateVar(myJmol, "{*}.xyz") );
  // Displays the coordinates of the geometric center of the model.
 alert( Jmol.evaluateVar(myJmol, "{*}.length") );
  // Displays the total number of atoms in the model.
 alert( Jmol.evaluateVar(myJmol, "{carbon}.bonds.length.min") );
  // Displays the minimum bond length between carbon atoms.
 alert( Jmol.evaluateVar(myJmol, "_atomPicked") );
  // Displays 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.

===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.

Definition: <code>Jmol.getPropertyAsArray = function(JmolObject,sKey,sValue)</code>

Examples:
 var atoms = Jmol.getPropertyAsArray(myJmol, "atomInfo", "all");
 var atom1 = atoms[0];
 var x = atom1.x;
 var info = atom1.info; 

===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. 

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.

Definition:  <code>Jmol.getPropertyAsJavaObject = function(JmolObject,sKey,sValue)</code>

Example:
 var viewer = jmolGetPropertyAsJavaObject("jmolViewer")
 var radius = viewer.getRotationRadius() 

Many of these public methods are listed in [{{SVN Trunk}}Jmol/src/org/jmol/api/JmolViewer.java JmolViewer.java]

===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. 

Definition:  <code>Jmol.getPropertyAsJSON = function(JmolObject,sKey,sValue)</code> 

Example:
 var info = Jmol.getPropertyAsJSON(myJmol, "filename") // {"filename": "file:/C:/data/caffeine.xyz"}

===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.

Definition:  <code>Jmol.getPropertyAsString = function(JmolObject,sKey,sValue)</code>

Examples:
 var s = Jmol.getPropertyAsString(myJmol, 'stateInfo');
 img.src = 'data:image/jpeg;base64,' + Jmol.getPropertyAsString(myJmol, 'image');

=== loadFileFromDialog ===
:''new in Jmol 14.6''

Opens a dialog asking for a file to be loaded, either from local disk or from a url. It may be a model file or a script or a data file. (The load operation will be run asynchronously.)

Definition: <code>Jmol.loadFileFromDialog = function(JmolObject)</code>

Example (attached to a button):
 <input type="button" value="Load a file" onClick="Jmol.loadFileFromDialog(myJmol)">
or
 Jmol.jmolButton(myJmol, function() { Jmol.loadFileFromDialog(myJmol) }, "Load a file");

===  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).

Definition: <code>Jmol.script = function(JmolObject, myScript)</code>

<tt>myScript</tt> (a text string containing one or several Jmol commands) is placed on the script queue.

Examples:
 Jmol.script(myJmol, "spacefill off; wireframe 0.3;");
 Jmol.script(myJmol, "script someScript.spt;");

=== 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>.

Definition: <code>Jmol.scriptEcho = function(JmolObject, myScript)</code>

Example:
 alert(Jmol.scriptEcho(myJmol, "show file"))

=== scriptWait ===

Runs a script synchronously, similarly to <code>scriptEcho()</code>, but returns a string including messages.

'''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:

<code>
 x = Jmol.evaluateVar(myJmol, "script('background red; print backgroundColor')")
</code>

will assign the string <code>[xff0000]</code> to the JavaScript variable <code>x</code>.


Definition: <code>Jmol.scriptWait = function(JmolObject, myScript)</code>

Example 1:
 x = Jmol.scriptWait(myJmol, "background red")

Runs that command and also returns this in the JavaScript variable <code>x</code>:
<pre>
2,scriptStatus,0,script 2 started
4,scriptStatus,0,Script completed
6,scriptStatus,0,Jmol script terminated
5,scriptTerminated,1,Jmol script terminated successfully
1,scriptStarted,2,background red;print backgroundColor
3,scriptEcho,0,[xff0000]
</pre>

Example 2:
 Jmol.scriptWait(myJmol, "backgroundred")

does nothing --since the command is incorrect, note the typo-- and returns this in the JavaScript variable <code>x</code>:
<pre>
2,scriptStatus,0,script 15 started
3,scriptStatus,0,script ERROR: command expected
----
        &gt;&gt; backgroundred &lt;&lt;
4,scriptStatus,0,Script completed
5,scriptTerminated,1,Jmol script terminated successfully
7,scriptTerminated,1,Jmol script terminated unsuccessfully: Jmol script terminated
1,scriptStarted,15,backgroundred
6,scriptError,0,Jmol script terminated
</pre>



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:

<code>
function myCallback(app,param1,param2,....) {
  setTimeout(function() {
    ...your JavaScript callback code here, including Jmol.scriptWait()...
  },10);
}
</code>

== 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.

=== getInfo ===
 Jmol.getInfo = function(JmolObject)
Use instead <code>Jmol.getPropertyAsArray(myJmol, "appletInfo")</code>

=== getStatus ===
 Jmol.getStatus = function(JmolObject, strStatus)
Deprecated.

=== loadFile ===
 Jmol.loadFile = function(JmolObject, fileName, params)
Use instead <code>Jmol.script(myJmol, "load '" + fileName + "'....")</code>

=== say ===
 Jmol.say = function(msg)
Use just <code>alert(msg)</code>

=== saveOrientation ===
 Jmol.saveOrientation = function(JmolObject, id)
Use instead <code>Jmol.script(myJmol, "saveOrientation " + id)</code>

=== restoreOrientation ===
 Jmol.restoreOrientation = function(JmolObject, id)
Use instead <code>Jmol.script(myJmol, "restore orientation " + id)</code>

=== restoreOrientationDelayed ===
 Jmol.restoreOrientationDelayed = function(JmolObject, id, delay)
Use instead <code>Jmol.script(myJmol, "restore orientation " + id + " " + delay)</code>

=== scriptMessage ===
 Jmol.scriptMessage = function(JmolObject, script)
Use instead Jmol.scriptWait(....)

=== scriptWaitAsArray ===
 Jmol.scriptWaitAsArray = function(JmolObject, script)
Deprecated.

=== scriptWaitOutput ===
 Jmol.scriptWaitOutput = function(JmolObject, script)
Same as <code>Jmol.scriptWait()</code>; deprecated; see <code>Jmol.scriptEcho()</code>

=== search ===
 Jmol.search = function(JmolObject, query, script)
Use instead <code>Jmol.script(myJmol, "load $caffeine")</code> for example.

== Methods specific to optional components ==
* [[Jmol_JavaScript_Object/JME|Methods specific to the JME applet]]
* [[Jmol_JavaScript_Object/JSV|Methods specific to the JSpecView applet]]