Difference between revisions of "Jmol JavaScript Object/Info"

From Jmol
Jump to navigation Jump to search
(Callbacks)
(update on the use of arguments array)
 
(37 intermediate revisions by the same user not shown)
Line 1: Line 1:
 +
<div style="float:right;">
 +
__TOC__
 +
</div>
 
= Documentation of parameters of the Info variable =
 
= Documentation of parameters of the Info variable =
  
Line 22: Line 25:
  
 
An alphabetic listing of all parameters, along with a comparative view of which modalities of Jmol Object they may be applied to, may be checked in [[Jmol JavaScript_Object/InfoTable]].
 
An alphabetic listing of all parameters, along with a comparative view of which modalities of Jmol Object they may be applied to, may be checked in [[Jmol JavaScript_Object/InfoTable]].
 
__TOC__
 
  
 
== Jmol object definition ==
 
== Jmol object definition ==
Line 42: Line 43:
  
 
=== Files and paths ===
 
=== Files and paths ===
* '''jarFile''' <code>"JmolApplet0.jar"</code>
 
:''(Java modality only)'' The file to be used, usually either <code>JmolApplet0.jar</code> (for faster incremental loading) or <code>JmolApplet.jar</code> (a single 2.5+ MB download), or the signed versions <code>JmolAppletSigned0.jar</code> and <code>JmolAppletSigned.jar</code>. Be careful that the setting here should match that of '''isSigned'''.
 
* '''isSigned''' <code>false</code>
 
:''(Java modality only)'' Make sure to change this to <code>true</code> if the file indicated for '''jarFile''' is the signed applet.
 
* '''jarPath''' <code>"java"</code>
 
:''(Java modality only)'' The path to the applet files. Note that if the unsigned applet is used and the page is tested locally, then all model files must be in or under the folder indicated by this value, to satisfy Java security policy.
 
 
* '''j2sPath''' <code>"j2s"</code>
 
* '''j2sPath''' <code>"j2s"</code>
 
:''(HTML5 modality)'' The path to {{folder|j2s}} including its own name; the contents of this folder are essential for JSmol to work.
 
:''(HTML5 modality)'' The path to {{folder|j2s}} including its own name; the contents of this folder are essential for JSmol to work.
 
* '''serverURL''' <code>"<nowiki>http://your.server.here/jsmol.php</nowiki>"</code>
 
* '''serverURL''' <code>"<nowiki>http://your.server.here/jsmol.php</nowiki>"</code>
:The URL of {{file|jsmol.php}} to be used for getting file data into non-Java modalities. For better performance and to avoid cross-domain issues, you should set this to a url in your same server. In the scheme of the standard JSmol distribution, that will be <code>"<nowiki>php/jsmol.php</nowiki>"</code>. If you cannot have PHP working in your server, you may use <code>"<nowiki>http://chemapps.stolaf.edu/jmol/jsmol/php/jsmol.php</nowiki>"</code>, since that is a public site accessible to cross-domain AJAX calls. Setting this properly is essential, among other situations, for loading binary files into JSmol in some browsers.
+
:The URL of {{file|jsmol.php}} to be used for getting file data into non-Java modalities. For better performance and to avoid cross-domain issues, '''you should set this''' to a url in the same server your pages are. In the scheme of the standard JSmol distribution, that will be <code>"<nowiki>php/jsmol.php</nowiki>"</code>.  
 +
:If you cannot have PHP working in your server, you may use <code>"<nowiki>https://chemapps.stolaf.edu/jmol/jsmol/php/jsmol.php</nowiki>"</code>, since that is a public site accessible to cross-domain AJAX calls.  
 +
:'''Setting this properly is essential''', among other situations,
 +
:* when loading into JSmol models in binary files, at least in some browsers
 +
:* for cross-domain loading JSmol components (<code>.js</code> files), i.e. when <code>Info.j2sPath</code>  points to a server different to the one that hosts the page
  
 
=== Modality ===
 
=== Modality ===
* '''use''' <code>"HTML5 noJava WebGL noImage"</code> This string determines the various options to be tried (applet and surrogates) and the order in which to try them.
+
* '''use''' <code>"HTML5"</code> This string determines the mode to be used (either Java applet or a surrogates).
** The default setting is the same as just <code>HTML5</code> by itself and indicates to use JSmol in html5-only mode.
+
** The default setting is <code>HTML5</code> and indicates to use JSmol in html5-only mode.
** The value <code>Java</code> forces use of the Jmol Applet (and it may display a message if Java is not enabled).  
+
** The value <code>WebGL</code> will force the [[Jmol_JavaScript_Object/WebGL|WebGL modality]] (combined with html5). ''Note that the WebGL version of JSmol does not implement the full set of functionalities of Jmol.''
** The value <code>Java HTML5</code> would test for Java and then, if that is not available, use JSmol.
+
** The value <code>Java</code> forces use of the Jmol Applet (and it may display a message if Java is not enabled). ''Note that Java applets are no longer supported by the majority of web browsers.''
** A value of <code>Java Image</code> would allow PNGJ files to be displayed as images or simple file loading to be delivered as an image from a server if Java is not available.
 
** The value <code>Java HTML5 WebGL Image</code> would try sequentially those modalities.
 
Note that Jmol-JSO cannot detect if the user has intentionally disabled Java in some browsers. Thus, users intentionally disabling Java may only get the Java modality, and a message will be displayed that Java is not available.
 
  
 
== Startup period ==
 
== Startup period ==
 
(The values shown in the listing below are the defaults)
 
(The values shown in the listing below are the defaults)
  
 +
* '''appletLoadingImage''' <code>j2sPath + "/img/JSmol_spinner.gif"</code>
 +
:Set the path and filename of an image that is displayed in place of the Jmol object while this is loading.
 +
:It may be disabled using <code>Info.appletLoadingImage = "none"</code>
 
* '''coverImage''' <code>""</code>  
 
* '''coverImage''' <code>""</code>  
:Set the path and filename of an image that will be displayed on top of the Jmol object (usually as an initial replacemente or during loading, see <code>deferApplet</code> and <code>deferUncover</code> parameters below).
+
:Set the path and filename of an image that will be displayed on top of the Jmol object (usually as an initial replacement or during loading, see <code>deferApplet</code> and <code>deferUncover</code> parameters below).
 +
* '''makeLiveImage''' <code>j2sPath + "/img/play_make_live.jpg"</code>
 +
:Set the path and filename of a small image (icon) that is displayed over the bottom-left corner of the cover image to give a visual hint that clicking will uncover the model. The default icon, [[File:Play make live.jpg]], is included in the JSmol distribution; you may specify your own using this parameter.
 
* '''coverTitle''' <code>""</code>  
 
* '''coverTitle''' <code>""</code>  
 
:Set a tip that is displayed before model starts to load.
 
:Set a tip that is displayed before model starts to load.
* '''coverCommand''' <code>""</code>  
+
* '''coverScript''' <code>""</code>  
 
:Set a Jmol command or script that will be executed upon clicking the cover image.
 
:Set a Jmol command or script that will be executed upon clicking the cover image.
 
* '''deferApplet''' <code>false</code>
 
* '''deferApplet''' <code>false</code>
Line 75: Line 76:
 
* '''deferUncover''' <code>false</code>
 
* '''deferUncover''' <code>false</code>
 
:If set <code>true</code>, the cover image will remain until command execution is complete.
 
:If set <code>true</code>, the cover image will remain until command execution is complete.
* '''disableInitialConsole''' <code>false</code>
+
* '''disableInitialConsole''' <code>true</code>
:If set <code>true</code>, avoids the display of messages ('console') in the Jmol panel while the Jmol object is being built initially.
+
:If set <code>false</code>, displays messages ('console') in the Jmol panel while the Jmol object is being built initially. Note: the default used to be <code>false</code> but was changed since version 14.5.2_2016.02.14, given the implementation of <code>appletLoadingImage</code>
 
* '''disableJ2SLoadMonitor''' <code>false</code>
 
* '''disableJ2SLoadMonitor''' <code>false</code>
 
:If set <code>true</code>, avoids the display of messages in a single line, colored, at bottom-left of the page while code loads (both initially and every time a new module is requested by a running script).
 
:If set <code>true</code>, avoids the display of messages in a single line, colored, at bottom-left of the page while code loads (both initially and every time a new module is requested by a running script).
Line 94: Line 95:
 
* '''script''' <code>""</code>  
 
* '''script''' <code>""</code>  
 
:A script to run when the Jmol object has finished loading. Note that indicating a script here is not necessary; with Jmol-JSO, unlike with Jmol.js, you can start making script calls to Jmol as soon as the Jmol wrapper object has been created in JavaScript; there is no need to wait for Jmol object initialization to have completed.  
 
:A script to run when the Jmol object has finished loading. Note that indicating a script here is not necessary; with Jmol-JSO, unlike with Jmol.js, you can start making script calls to Jmol as soon as the Jmol wrapper object has been created in JavaScript; there is no need to wait for Jmol object initialization to have completed.  
 +
: Note that using <code>script</code> will cancel whatever <code>src</code> specifies (but it is easy to include a <code>load</code> command as part of the script)
 
* '''defaultModel''' <code>""</code>  
 
* '''defaultModel''' <code>""</code>  
 
:The name or id of a model to be retrieved from a public database, and displayed when the Jmol object has finished loading.  
 
:The name or id of a model to be retrieved from a public database, and displayed when the Jmol object has finished loading.  
Line 107: Line 109:
 
* '''addSelectionOptions''' <code>false</code>
 
* '''addSelectionOptions''' <code>false</code>
 
:Set this value to <code>true</code> if you want to display, below the Jmol object, a menu with options for loading structures from public databases.
 
:Set this value to <code>true</code> if you want to display, below the Jmol object, a menu with options for loading structures from public databases.
 +
* '''allowJavaScript''' <code>true</code>
 +
:Set this value to <code>false</code> if you want to prevent any JavaScript command being run from JSmol (using the [{{ScriptingDoc}}#javascript javascript] command or [{{ScriptingDoc}}#set_evalcallback_top EvalCallback]). Note: this feature is offered because allowing any arbitrary javascript may be considered a security risk in some environments.
 
* '''console''' <code>"***_infodiv"</code>
 
* '''console''' <code>"***_infodiv"</code>
:The ID in html of the container or div that will receive output from Jmol. Default value is the Jmol Object name/id followed by "_infodiv", and it is contained in the info panel that may be displayed alternatively to the Jmol viewer.
+
:The ID in html of the container or div that will receive output from JSmol. Default value is the JSmol Object name/id (represented here by ***) followed by <code>_infodiv</code>, and it is contained in the info panel that may be displayed alternatively to the JSmol viewer.
 
* '''debug''' <code>false</code>
 
* '''debug''' <code>false</code>
 
:Set this value to <code>true</code> if you are having problems getting your page to show the Jmol object, buttons or ther controls.
 
:Set this value to <code>true</code> if you are having problems getting your page to show the Jmol object, buttons or ther controls.
Line 116: Line 120:
 
::<code>language: "es"</code>  for Spanish
 
::<code>language: "es"</code>  for Spanish
 
::<code>language: "pt_BR"</code>  for Brazilian Portuguese
 
::<code>language: "pt_BR"</code>  for Brazilian Portuguese
* '''memoryLimit''' <code>512</code>
 
:''(Java modality only)'' The maximum amount of memory allowed for the Java applet, in MB.
 
 
* '''menuFile''' "''fileName''"
 
* '''menuFile''' "''fileName''"
 
:Loads a [[Custom Menus|custom pop-up menu]].
 
:Loads a [[Custom Menus|custom pop-up menu]].
* '''usecommandthread''' <code>false</code>
 
:The signed Jmol Java applet generally runs commands by passing them to a command thread that is established when the applet is created, while the unsigned applet does not. You can change this behavior if you are observing Java security issues. Otherwise, it should not be adjusted.
 
 
* '''zIndexBase''' <code>9000</code>
 
* '''zIndexBase''' <code>9000</code>
 
:Defines the z-index property in CSS of the Jmol Object and its associated div's. This is set by default to a very high value, so the object will be laid on top of any other page elements, but it may be useful to change it when you are integrating Jmol with other components. In addition to setting for the particular applet, it also sets the default for all other applets on the page, in case it is not defined for those applets.
 
:Defines the z-index property in CSS of the Jmol Object and its associated div's. This is set by default to a very high value, so the object will be laid on top of any other page elements, but it may be useful to change it when you are integrating Jmol with other components. In addition to setting for the particular applet, it also sets the default for all other applets on the page, in case it is not defined for those applets.
Line 157: Line 157:
 
== Callbacks ==
 
== 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 <code>function() {....}</code> syntax.
+
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 function, wrapped in single- or double-quotes, should be given as value. This may be:
 +
* A JavaScript function. Do not use <code>function() {....}</code> syntax.
 +
* A Jmol script (preceded by the token <code>jmolscript:</code> )
  
 
:(In the former method, Jmol.js, these could be set using either <code>jmolSetParameter()</code> or <code>jmolSetCallback()</code> functions.)
 
:(In the former method, Jmol.js, these could be set using either <code>jmolSetParameter()</code> or <code>jmolSetCallback()</code> functions.)
  
As an alternative, the callbacks may also be defined from a script using the [{{ScriptingDoc}}#setcallback<code>set</code>] command.
+
Example 1:
 
 
Example:
 
 
  Info.pickCallback = "myPick";
 
  Info.pickCallback = "myPick";
 
  function myPick() {
 
  function myPick() {
Line 172: Line 172:
 
# the first parameter returned (argument zero) is always the Jmol Object name;
 
# the first parameter returned (argument zero) is always the Jmol Object name;
 
# the 2nd and later parameters hold the information; not all are used by all callbacks (see below).
 
# the 2nd and later parameters hold the information; not all are used by all callbacks (see below).
 +
Note that the array of arguments is zero-based in JavaScript but 1-based in JmolScript.
 +
 +
A [http://biomodel.uah.es/Jmol/callbacks/ test page] where the output of some of the callbacks may be examined is available.
 +
 +
 +
As an alternative, the callbacks may also be defined from a script using the [{{ScriptingDoc}}#setcallback<code>set</code>] command.
 +
In this case, the parameters will be available in an <code>_arguments</code> array and an <code>_argumentCount</code> variable is also available. <code>_args()</code> and <code>_args(n)</code> are synonyms for <code>_arguments</code> and <code>_arguments[n]</code> to be used in functions, scripts, and callbacks.
 +
 +
Example 2:
 +
Info.pickCallback = "jmolscript:print 'atom is ' + _arguments[2]";
 +
 +
 +
In the descriptions below, it is assumed that we are using a JavaScript function for the callback.
  
* '''animFrameCallback'''
+
=== 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).
+
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[1]: frame index (zero-based).
 
: arguments[2]: file number (1-based).
 
: arguments[2]: file number (1-based).
Line 184: Line 197:
 
: 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[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
 
: 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 <code>readyFunction</code> parameter described above.  
+
=== appletReadyCallback ===
<!--: Called: when creation of the Jmol Object in the page has finished.
+
Please, do not use this. Instead, use the <code>readyFunction</code> parameter described above.  
 +
<!--Called: when creation of the Jmol Object in the page has finished.
 
: arguments[1]: the Jmol Object name, followed by two underscores, the unique ID of that particular object (a 16-digit random number) and two underscores.
 
: arguments[1]: the Jmol Object name, followed by two underscores, the unique ID of that particular object (a 16-digit random number) and two underscores.
 
: arguments[2]: a boolean value (true/false, presumably indicating successful creation of the Jmol Object).
 
: arguments[2]: a boolean value (true/false, presumably indicating successful creation of the Jmol Object).
 
: arguments[3]: a JavaScript object of the Jmol type.
 
: arguments[3]: a JavaScript object of the Jmol type.
: ''See also'' the <code>readyFunction</code>  parameter above, as an alternative solution.
+
''See also'' the <code>readyFunction</code>  parameter above, as an alternative solution.
 
-->
 
-->
  
* '''atomMovedCallback'''
+
=== atomMovedCallback ===
* '''echoCallback'''
+
Called: when the position of one or more atoms is modified; this usually requires <code>set picking dragatom</code> + mouse action, or <code>rotateSelected</code> or similar command.
* '''evalCallback'''
+
: arguments[1]: the affected atom set (as a Jmol atomset object - possibly in JSON construction; this will need parsing)
* '''hoverCallback'''
+
 
: Called: when the mouse or pointer is positioned (hovers) over an atom.
+
=== dragDropCallback ===
 +
Called: when a file is dropped into the Jmol panel
 +
: arguments[1]: a number ''(this needs explanation)''
 +
: arguments[2]: x (coordinate within the Jmol panel where the pointer was released at dropping)
 +
: arguments[3]: y (coordinate)
 +
: arguments[4]: the file name (preceded by "cache://DROP_")
 +
: arguments[5]: an array (with a single null)
 +
In addition (Jmol version 14.32.58 or later), when a file is dropped this global user variables will be set:
 +
* <code>dropFileType</code> which can be read and also changed within the callback handler function
 +
* <code>dropFileName</code> (preceded by "cache://DROP_")
 +
* <code>doDrop</code>, initially TRUE; if set to FALSE within the callback handler function, it will prevent the file from being loaded.
 +
 
 +
=== echoCallback ===
 +
Called: when Jmol produces some output from an <code>echo</code> command, or a <code>show</code> 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 [{{ScriptingDoc}}#javascript<code>javascript</code>] command is used (and is not forbidden by a setting of <code>Info.allowJavaScript = false</code>), this callback sends the JavaScript back to the web page for evaluation rather than initiating that evaluation within Jmol. For more details, see [{{ScriptingDoc}}#setcallback<code>set EvalCallback</code>]
 +
 
 +
=== 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 <code>set hoverLabel</code>), followed by X, Y, Z coordinates of the atom.
 
: arguments[1]: a text string with the current hover label (either the default or user-defined through <code>set hoverLabel</code>), followed by X, Y, Z coordinates of the atom.
 
:: Example for a MOL file: <code>O14 #14 -0.438 -2.4279 -0.0068</code>  
 
:: Example for a MOL file: <code>O14 #14 -0.438 -2.4279 -0.0068</code>  
 
:: Example for a PDB file: <code>[ASN]46:A.ND2 #326 13.407 3.298 15.015</code>  
 
:: Example for a PDB file: <code>[ASN]46:A.ND2 #326 13.407 3.298 15.015</code>  
 
: arguments[2]: the atom index (zero-based)
 
: arguments[2]: the atom index (zero-based)
* '''loadStructCallback'''
+
 
: Called: upon file loading (successful or not).
+
=== loadStructCallback ===
 +
Called: upon file loading (successful or not).
 
: arguments[1]: the URL of the loaded file (full path+filename).
 
: arguments[1]: the URL of the loaded file (full path+filename).
 
: arguments[2]: the filename of the loaded file (without the path).
 
: arguments[2]: the filename of the loaded file (without the path).
Line 211: Line 248:
 
: 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[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.
 
: 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
+
Note: When multiple files are loaded with the same load command, only data for the last-loaded file is returned
* '''measureCallback'''
+
 
* '''messageCallback'''
+
=== measureCallback ===
* '''minimizationCallback'''
+
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
* '''pickCallback'''
+
: 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:
: Called: when the user clicks an atom -- or a bond (see below).
+
:: <code>[H18 #18, O4 #4]</code> for a distance (MOL file)
: Note that for this to work, <code>set atomPicking</code> must be set true (it is by default)
+
:: <code>[H18 #18, O4 #4, H16 #16]</code> for an angle (MOL file)
: arguments[1]: atom id, atom number, and xyz coordinates in the form:
+
:: <code>[[ILE]7:A.CD1 #47, [ASN]46:A.ND2 #326]</code> for a distance (PDB file)
:: <code>C6 #6 -0.30683374 -1.6836332 -0.716934</code>
+
:: <code>[[ILE]34:A.CD1 #245, [ILE]34:A.CG1 #243, [ILE]34:A.CB #242]</code> for an angle (PDB file)
: arguments[2]: atom index (zero-based).  
+
 
 +
: 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 <code>measurePending</code>; when measurement is finished, <code>measureCompleted</code>
 +
: 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 <code>minimize</code> command or the pop-up menu entry under <code>calculation</code>, 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, <code>set atomPicking</code> must be set true (it is by default).
 +
 
 +
Also, note that this description applies to the standard <code>set picking ident</code>; 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) <code>C6 #6 -0.307 -1.684 -0.717</code>
 +
:: (PDB file) <code>[TYR]29:A.CE2 #210 -0.801 7.705 5.156</code>
 +
: arguments[2]: an object with the single property <code>valueOf()</code>, whose result is the atom index (zero-based). Alternatively, the index as a JavaScript string may be obtained using <code>&quot;&quot; + arguments[2]</code>.
 +
: arguments[3]: a null or empty object.  
  
 +
* '''Clicking on a bond:'''
 
:If <code>set bondPicking true</code> has been issued, bonds will become clickable and also invoke the callback function, but the return from the function will be different:
 
:If <code>set bondPicking true</code> 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:
 
: arguments[1]: a text string in the form:
:: <code>["bond","3 1 C2 #2 -- C4 #4 1.3608072",-0.0,0.9061,-0.30629998]</code>
+
:: (MOL file) <code>["bond","3 1 C2 #2 -- C4 #4 1.361",-0.0,0.906,-0.306]</code>
:: meaning ?, ?, atom id, atom number, atom id, atom number, bond length (distance), ?, ?, ?.
+
:: 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) <code>["bond","329 1 [ASN]46:A.N #319 -- [ALA]45:A.C #316 1.32",14.57,6.52,14.01]</code>
 
: arguments[2]: ?.  
 
: arguments[2]: ?.  
: arguments[3]: a text string in the form:
+
: arguments[3]: an object with these properties:
:: <code>{model=1.1, index=2, type=bond, info=3 1 C2 #2 -- C4 #4 1.3608072, pt={-0.0, 0.9061, -0.30629998}, modelIndex=0}</code>
+
::: <code>model</code> e.g. 1.1  
+
::: <code>index</code> e.g. 328
* '''resizeCallback'''
+
::: <code>type</code> 'bond'
* '''scriptCallback'''
+
::: <code>info</code> 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)
* '''syncCallback'''
+
::: <code>pt</code> xyz coordinates of the bond's midpoint, e.g. {14.57, 6.52, 14.01}  
 +
::: <code>modelIndex</code> (e.g. 0 )
 +
 
 +
=== resizeCallback ===
 +
Called: when the JSmol object div size is changed. If the resizing is done with <code>Jmol.resizeApplet()</code>, 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 [{{ScriptingDoc}}#setcallback<code>set StructureModifiedCallback</code>].
 +
 
 +
=== syncCallback ===
 +
Called: when the Jmol object issues/receives (?) a synchronization message to/from (?) another Jmol object (see the [{{ScriptingDoc}}#sync <code>sync</code> 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.
  
 
== Lightweight version ==
 
== Lightweight version ==
Line 249: Line 338:
 
* '''progresscolor'''
 
* '''progresscolor'''
 
:These five values generally should not be adjusted.
 
:These five values generally should not be adjusted.
 +
 +
The following are deprecated since they only applied to the Java modality (Jmol Java applet):
 +
 +
* '''jarFile''' <code>"JmolApplet0.jar"</code>
 +
:''The file to be used, usually either <code>JmolApplet0.jar</code> (for faster incremental loading) or <code>JmolApplet.jar</code> (a single 2.5+ MB download), or the signed versions <code>JmolAppletSigned0.jar</code> and <code>JmolAppletSigned.jar</code>. Be careful that the setting here should match that of '''isSigned'''.
 +
* '''isSigned''' <code>false</code>
 +
:Make sure to change this to <code>true</code> if the file indicated for '''jarFile''' is the signed applet.
 +
* '''jarPath''' <code>"java"</code>
 +
:''The path to the applet files. Note that if the unsigned applet is used and the page is tested locally, then all model files must be in or under the folder indicated by this value, to satisfy Java security policy.
 +
* '''memoryLimit''' <code>512</code>
 +
:The maximum amount of memory allowed for the Java applet, in MB.
 +
* '''usecommandthread''' <code>false</code>
 +
:The signed Jmol Java applet generally runs commands by passing them to a command thread that is established when the applet is created, while the unsigned applet does not. You can change this behavior if you are observing Java security issues. Otherwise, it should not be adjusted.

Latest revision as of 09:36, 1 August 2023

Documentation of parameters of the Info variable

This page explains the parameters of the Info variable, an essential part of the Jmol JavaScript Object and hence of JSmol.

Note that, although this is usually designated as Info in the documentation, it is a regular JavaScript variable that you can name as you wish.

Info is an associative array (a set of key/value pairs) indicating all the desired characteristics of the Jmol object (Jmol applet or JSmol).

Values may be defined

  • either during initialization of the Info variable:
  var Info = {
    color: "#E8F4FF",
    height: 400,
    width: 400
  };
  • or separately:
  Info.color = "#E8F4FF";

An alphabetic listing of all parameters, along with a comparative view of which modalities of Jmol Object they may be applied to, may be checked in Jmol JavaScript_Object/InfoTable.

Jmol object definition

(The values shown in the listing below are the defaults)

Dimensions

  • height 300
The size of the Jmol object in pixels or expressed as percent of its container height as a string in quotes: "100%".
  • width 300
The width of the Jmol object in pixels or expressed as percent of its container width as a string in quotes: "100%".

Note that for a percent to work, all surrounding HTML elements must explicitly implement the CSS attributes style=height:... and style=width:.... That includes setting height to 100% for body and html. Note also that, despite that, non-Java JSmol uses the canvas element, which will not resize correctly.

Background color

  • color "white"
The background color of the Jmol object, as a quoted text string in any JmolScript-supported format: color name, decimal triplet [r,g,b] or hexadecimal [xRRGGBB], or in html-style format: #RRGGBB. Note that default is now white, in contrast to black in the classic Jmol.js method.

Files and paths

  • j2sPath "j2s"
(HTML5 modality) The path to Folder icon.gifj2s including its own name; the contents of this folder are essential for JSmol to work.
  • serverURL "http://your.server.here/jsmol.php"
The URL of File icon.gifjsmol.php to be used for getting file data into non-Java modalities. For better performance and to avoid cross-domain issues, you should set this to a url in the same server your pages are. In the scheme of the standard JSmol distribution, that will be "php/jsmol.php".
If you cannot have PHP working in your server, you may use "https://chemapps.stolaf.edu/jmol/jsmol/php/jsmol.php", since that is a public site accessible to cross-domain AJAX calls.
Setting this properly is essential, among other situations,
  • when loading into JSmol models in binary files, at least in some browsers
  • for cross-domain loading JSmol components (.js files), i.e. when Info.j2sPath points to a server different to the one that hosts the page

Modality

  • use "HTML5" This string determines the mode to be used (either Java applet or a surrogates).
    • The default setting is HTML5 and indicates to use JSmol in html5-only mode.
    • The value WebGL will force the WebGL modality (combined with html5). Note that the WebGL version of JSmol does not implement the full set of functionalities of Jmol.
    • The value Java forces use of the Jmol Applet (and it may display a message if Java is not enabled). Note that Java applets are no longer supported by the majority of web browsers.

Startup period

(The values shown in the listing below are the defaults)

  • appletLoadingImage j2sPath + "/img/JSmol_spinner.gif"
Set the path and filename of an image that is displayed in place of the Jmol object while this is loading.
It may be disabled using Info.appletLoadingImage = "none"
  • coverImage ""
Set the path and filename of an image that will be displayed on top of the Jmol object (usually as an initial replacement or during loading, see deferApplet and deferUncover parameters below).
  • makeLiveImage j2sPath + "/img/play_make_live.jpg"
Set the path and filename of a small image (icon) that is displayed over the bottom-left corner of the cover image to give a visual hint that clicking will uncover the model. The default icon, Play make live.jpg, is included in the JSmol distribution; you may specify your own using this parameter.
  • coverTitle ""
Set a tip that is displayed before model starts to load.
  • coverScript ""
Set a Jmol command or script that will be executed upon clicking the cover image.
  • deferApplet false
If set true, the model will not be loaded until the user clicks on the cover image (see coverImage parameter above).
  • deferUncover false
If set true, the cover image will remain until command execution is complete.
  • disableInitialConsole true
If set false, displays messages ('console') in the Jmol panel while the Jmol object is being built initially. Note: the default used to be false but was changed since version 14.5.2_2016.02.14, given the implementation of appletLoadingImage
  • disableJ2SLoadMonitor false
If set true, avoids the display of messages in a single line, colored, at bottom-left of the page while code loads (both initially and every time a new module is requested by a running script).
  • readyFunction null
The name (without quotes) of a JavaScript function to call when the Jmol object has been created and is ready to receive commands (and also called when the object is destroyed e.g. when the page is closed).
For example, with readyFunction: jmolIsReady any of the following JavaScript function definitions could be used:
function jmolIsReady() { alert('Welcome to Jmol!'); }
jmolIsReady = function() { alert('Welcome to Jmol!'); }
jmolIsReady = function(theJmol) { document.title = theJmol._id + " is ready"; }
Note: The JavaScript function will receive as argument a pointer to the particular Jmol object that invoked it (as exemplified in the third example above).

Model loading

(The values shown in the listing below are the defaults)

  • src ""
A filename to load once the Jmol object has finished loading. It may be a model in a supported format, or a script file.
  • script ""
A script to run when the Jmol object has finished loading. Note that indicating a script here is not necessary; with Jmol-JSO, unlike with Jmol.js, you can start making script calls to Jmol as soon as the Jmol wrapper object has been created in JavaScript; there is no need to wait for Jmol object initialization to have completed.
Note that using script will cancel whatever src specifies (but it is easy to include a load command as part of the script)
  • defaultModel ""
The name or id of a model to be retrieved from a public database, and displayed when the Jmol object has finished loading.
Examples:
defaultModel: "=1crn" gets it from RCSB PDB
defaultModel: "$caffeine" gets it from NCI CACTUS
defaultModel: ":caffeine" gets it from PubChem
defaultModel: "caffeine" gets it from NCI CACTUS

Customization or extras

(The values shown in the listing below are the defaults)

  • addSelectionOptions false
Set this value to true if you want to display, below the Jmol object, a menu with options for loading structures from public databases.
  • allowJavaScript true
Set this value to false if you want to prevent any JavaScript command being run from JSmol (using the javascript command or EvalCallback). Note: this feature is offered because allowing any arbitrary javascript may be considered a security risk in some environments.
  • console "***_infodiv"
The ID in html of the container or div that will receive output from JSmol. Default value is the JSmol Object name/id (represented here by ***) followed by _infodiv, and it is contained in the info panel that may be displayed alternatively to the JSmol viewer.
  • debug false
Set this value to true if you are having problems getting your page to show the Jmol object, buttons or ther controls.
  • language "2-letter or 2+2-letter code"
This setting can be used to specify a language to be used in the Jmol Object interface (mainly the pop-up menu). The existing choices may be checked in the pop-up menu. If not specified, the default language is automatically detected from the system settings of the user's browser.
Examples:
language: "es" for Spanish
language: "pt_BR" for Brazilian Portuguese
  • menuFile "fileName"
Loads a custom pop-up menu.
  • zIndexBase 9000
Defines the z-index property in CSS of the Jmol Object and its associated div's. This is set by default to a very high value, so the object will be laid on top of any other page elements, but it may be useful to change it when you are integrating Jmol with other components. In addition to setting for the particular applet, it also sets the default for all other applets on the page, in case it is not defined for those applets.
  • z {9000, 9001, 9002, 9003, 9004, 9005, 9006, 9007, 99008, 100008, 109007}
Defines, in a more fine-grained way, the z-index property in CSS of all div's forming the Jmol Object.
It is an associative array that includes (some of these are more relevant to JmolSpecViewer):
Info.z = {
  header: ,
  rear: ,
  main: ,
  image: ,
  front: ,
  fileOpener: ,
  coverImage: ,
  dialog: ,
  menu: ,
  console: ,
  monitorZIndex:
}
When just zIndexBase is provided, it will set all components of z in this way:
  header: zIndexBase,
  rear: zIndexBase + 1,
  main: zIndexBase + 2,
  image: zIndexBase + 3,
  front: zIndexBase + 4,
  fileOpener: zIndexBase + 5,
  coverImage: zIndexBase + 6,
  dialog: zIndexBase + 7,
  menu: zIndexBase + 90000,
  console: zIndexBase + 91000,
  monitorZIndex: zIndexBase + 99999

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 function, wrapped in single- or double-quotes, should be given as value. This may be:

  • A JavaScript function. Do not use function() {....} syntax.
  • A Jmol script (preceded by the token jmolscript: )
(In the former method, Jmol.js, these could be set using either jmolSetParameter() or jmolSetCallback() functions.)

Example 1:

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

Note that the array of arguments is zero-based in JavaScript but 1-based in JmolScript.

A test page where the output of some of the callbacks may be examined is available.


As an alternative, the callbacks may also be defined from a script using the set command. In this case, the parameters will be available in an _arguments array and an _argumentCount variable is also available. _args() and _args(n) are synonyms for _arguments and _arguments[n] to be used in functions, scripts, and callbacks.

Example 2:

Info.pickCallback = "jmolscript:print 'atom is ' + _arguments[2]";


In the descriptions below, it is assumed that we are using a JavaScript function for the callback.

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)

dragDropCallback

Called: when a file is dropped into the Jmol panel

arguments[1]: a number (this needs explanation)
arguments[2]: x (coordinate within the Jmol panel where the pointer was released at dropping)
arguments[3]: y (coordinate)
arguments[4]: the file name (preceded by "cache://DROP_")
arguments[5]: an array (with a single null)

In addition (Jmol version 14.32.58 or later), when a file is dropped this global user variables will be set:

  • dropFileType which can be read and also changed within the callback handler function
  • dropFileName (preceded by "cache://DROP_")
  • doDrop, initially TRUE; if set to FALSE within the callback handler function, it will prevent the file from being loaded.

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 Info.allowJavaScript = false), 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 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.

Lightweight version

A special alternative version of JSmol may be invoked, with a very small file size and high responsiveness, particularly adequate for a quick startup and for systems with limited resources and power, like phones. It accepts a subset of the parameters described here, plus some additional, unique parameters. See Lightweight JSmol for details.


Misc.

  • boxbgcolor
  • boxfgcolor
  • boxmessage
  • progressbar
  • progresscolor
These five values generally should not be adjusted.

The following are deprecated since they only applied to the Java modality (Jmol Java applet):

  • jarFile "JmolApplet0.jar"
The file to be used, usually either JmolApplet0.jar (for faster incremental loading) or JmolApplet.jar (a single 2.5+ MB download), or the signed versions JmolAppletSigned0.jar and JmolAppletSigned.jar. Be careful that the setting here should match that of isSigned.
  • isSigned false
Make sure to change this to true if the file indicated for jarFile is the signed applet.
  • jarPath "java"
The path to the applet files. Note that if the unsigned applet is used and the page is tested locally, then all model files must be in or under the folder indicated by this value, to satisfy Java security policy.
  • memoryLimit 512
The maximum amount of memory allowed for the Java applet, in MB.
  • usecommandthread false
The signed Jmol Java applet generally runs commands by passing them to a command thread that is established when the applet is created, while the unsigned applet does not. You can change this behavior if you are observing Java security issues. Otherwise, it should not be adjusted.

Contributors

AngelHerraez