Jmol 脚本对象/函数
创建 JSmol 的 JS类型对象
语法:
Jmol.getApplet = function(id, Info, checkOnly)
此函数在网页的脚本空间中创建 Jmol 对象
Jmol.getApplet("myJmol", Info);
上面的示例将创建一个保存 Jmol 对象的 myJmol 变量,并且该对象将插入到页面中(除非 Jmol.setDocument() 已设置为 false,请参见下文)。
checkOnly是一个可选的参数,当设置时,它允许获取一个JavaScript对象,可以检查该对象以查看将在此特定平台上创建哪种类型的Jmol对象 - 签名的Java小程序,未签名的Java小程序,JSmol画布,图像,WebGL画布等。
如果你想在页面中有2个Jmol对象,你将用两次这个调用,在不同的位置和不同的名称:
Jmol.getApplet("jmolA", Info);
Jmol.getApplet("jmolB", Info);
创建JSmol 的html类型的对象
语法:
Jmol.getAppletHtml = function(JmolObject)
或者
Jmol.getAppletHtml = function(id, Info)
用于将 Jmol 对象代码插入页面,无论是在页面加载之后还是在对象生成并存储在变量中的情况下,例如在 Jmol.setDocument(0) 之后。它对于 window.onload 内的 .innerHTML 或由用户操作触发的函数(或 jQuery 等效项 .html() 和 $(document).ready)特别有用。一些例子:
简单使用
$(document).ready(function(){
$("#somePlace").html(Jmol.getAppletHtml("myJmol", Info));
});
[...]
<div id="somePlace"></div>
window.onload = function(){
document.getElementById("place1").innerHTML = Jmol.getAppletHtml("jmol1", Info);
document.getElementById("place2").innerHTML = Jmol.getAppletHtml("jmol2", Info);
});
先创建jmol对象再插入到页面上
window.onload = function(){
Jmol.setDocument(0);
Jmol.getApplet("jmol1", Info); // 创建jdmol对象但是不要插入到页面上
Jmol.getApplet("jmol2", Info);
[...] // 影像jsmol对象的其他操作
// 现在,把jmol对象插入到页面中:
document.getElementById("place1").innerHTML = Jmol.getAppletHtml(jmol1);
document.getElementById("place2").innerHTML = Jmol.getAppletHtml(jmol2);
});
上面的例子是页面加载时创建jsmol,其实也可以通过触发事件动态创建
function insertMyJmol(){
$("#myJmolContainer").html(Jmol.getAppletHtml("myJmol", Info));
});
<div id="myJmolContainer"></div>
<input type="button" value="show 3D structure" onClick="insertMyJmol()">
getVersion 获取版本
此函数返回 Jmol-JSO 的版本,如 Jmol-JSO 13.1.12。
var t = Jmol.getVersion(myJmol);
alert(t);
resizeApplet 调整大小
定义: Jmol.resizeApplet = function(JmolObject,size)
用于更改指定 Jmol 对象的尺寸。
size:数组中的一个值或一对宽度/高度值,以像素或百分比表示。
例子:
Jmol.resizeApplet(myJmol, 400);
Jmol.resizeApplet(myJmol, [400,700]);
Jmol.resizeApplet(myJmol, "100%");
Jmol.resizeApplet(myJmol, ["50%","60%"]);
setDocument设置文档
定义:Jmol.setDocument = function(doc)
doc 是必须在其中创建 Jmol 对象的目标 html 上下文。
如果使用 Jmol.setDocument(false) 或 Jmol.setDocument(0),则稍后可以使用 Jmol.getAppletHtml() 插入 Jmol 对象。发生的情况是对象的 HTML 代码被放入内部 applet._code 变量中,而不是写入页面。然后您仍然可以参考小程序,但在制作控件后将其放置在页面上,或者在某些用户操作时将 ot 注入页面。
例子:
Jmol.setDocument(false);
Jmol.getApplet("myJmol", Info);
(...)
document.getElementById('someContainer').innerHTML = Jmol.getAppletHtml(myJmol);
或者,使用 jQuery 语法;
Jmol.setDocument(false);
Jmol.getApplet("myJmol", Info);
(...)
$("#someContainer").html(Jmol.getAppletHtml(myJmol));
在某些情况下,这可能相当于一个更简单的替代方案:只需定义 Jmol 对象变量,如 var myJmol = “myJmol”,然后在提供任何选项或创建按钮和控件时,“myJmol” 就足够了。最后,使用 Jmol.getApplet(myJmol,…) 对象将起作用。
setGrabberOptions 获取选项
定义: Jmol.setGrabberOptions = function(options)
当使用 addSelectionOptions:true 时,允许自定义从数据库中获取分子的下拉菜单中提供的项目。例子:
Jmol.setGrabberOptions([
["$", "small molecules at NCI"],
[":", "small molecules at PubChem"],
["==", "ligands at PDB"],
["=", "macromolecules at PDB"]
])
每个元素中的第一个值是将请求定向到数据库的 JmolScript 前缀(无法自定义)。第二个值是显示在页面下拉菜单中的文本,位于 Jmol 对象下方。
showInfo显示信息
定义:Jmol.showInfo = function(JmolObject, tf)
这将显示或隐藏信息面板(它包含日志控制台,或者可能是关联的 JME 小程序)。默认情况下,该面板与 Jmol 查看器位于同一位置,因此显示 Info 将隐藏 Jmol,反之亦然。
tf 参数是一个真或假标志。
setInfo设置信息
定义:Jmol.setInfo = function(JmolObject, info, isShown)
将 Jmol 对象的信息 div 设置为 info (HTML) 并可选择显示它。
setXHTML
定义:Jmol.setXHTML = function(id)
指示将插入 Jmol 对象的 DOM 节点的 id,在创建页面元素时遵循 XHTML 格式。很大程度上未经测试。
例子:
<!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>
Functions for creating controls用于创建控件的函数
这些 Jmol 函数创建页面的元素,页面访问者可以使用这些元素与 applet 或 applet 代理进行交互。同样,所有这些函数都必须应用于唯一的 Jmol 构造函数(这个名称是字面的,不能更改)——请参见下面的语法和示例。
几乎所有这些函数的第一个参数 JmolObject 必须是对将接收控件操作的对象的引用。这样的引用要么是 JSO 对象本身,要么是它的 name-id(例如上面示例中的“myJmol”)。
jmolButton
在页面中插入一个带有文本内容的按钮。
定义:Jmol.jmolButton(JmolObject, script, label, id, title)
例子:
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");
script 按下按钮时运行脚本。作为一种特殊语法(对任何其他控件以及此处描述的按钮有效),您可以运行您定义的 JavaScript 函数,而不是 Jmol 脚本,方法是提供此函数来代替脚本:[funcName, param1, param2 , param3…] 函数必须这样定义:
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.
....
}
label 是按钮中的文本;如果未指定,则默认为脚本的前 32 个字符。
id(可选)将设置为 HTML id 和 HTML 名称。它将默认为 jmolButton0、jmolButton1 等。
title :
此外,该按钮将包含在 元素中,该元素的 HTML id 为“span_”加上给定的 id,以及给定标题的 HTML 标题。
因此,当鼠标指针停留在按钮上时,浏览器会将标题显示为工具提示。
jmolCheckbox
定义:
Jmol.jmolCheckbox(JmolObject, scriptWhenChecked, scriptWhenUnchecked, labelHtml, isChecked, id, title)
在页面中插入一个复选框,然后紧跟 labelHtml。
scriptWhenChecked 在用户选中复选框时运行。
scriptWhenUnchecked 在用户取消选中复选框时运行。
isChecked 如果您希望在页面加载时选中或标记复选框(默认值:未选中),则应将 isChecked 设置为非 false 值(例如:true)。
id 将被设置为 HTML id 和 HTML 名称。它将默认为 jmolCheckbox0、jmolCheckbox1 等。
title 当鼠标指针停留在复选框或其随附的 labelHtml 上时,浏览器会将标题显示为工具提示。
例子:
Jmol.jmolCheckbox(myJmol,"spacefill on","spacefill off","toggle display as spheres");
setCheckboxGroup设置复选框组
定义: Jmol.setCheckboxGroup(chkMaster,chkBoxes)
从先前插入的复选框开始(使用 Jmol.jmolCheckbox()),这允许根据以下规则在一个“父”或“领导”复选框与一个或多个“子”或“跟随”复选框之间建立关系:
每当检查领导者时,它的所有追随者都会自动检查。
每当领导者未选中时,其所有追随者都会自动取消选中。
每当检查或取消检查其中一个追随者时,都会检查其兄弟姐妹;如果都具有相同的状态,则将相应地检查或取消检查领导者。如果它们有混合状态,则领导者将具有“部分检查”状态;这种部分选中的框的显示样式取决于浏览器(阅读更多)。
插入/定义时与每个复选框关联的 Jmol 脚本将在其状态由于对主复选框的操作而发生更改时执行。因此,可能不需要将任何脚本附加到主复选框,而只需执行子项的脚本即可。
chkMaster 是为将充当领导者的复选框提供的 ID。此 ID 可能已在其 Jmol.jmolCheckbox()) 定义中指定,也可能是一个数字(如果未指定 ID,则默认分配顺序数字 ID,从零开始)。
chkBoxes 是一个或多个 ID 或数字的数组,指向将充当跟随者的复选框。或者,它可以是以逗号分隔的 ID 列表作为文本字符串。
请参阅代码示例。
可以在一个页面中设置任意数量的组,并带有任意数量的组件复选框。在其他组中嵌套组也是可能的(即,一个组中的追随者可能是内部组的领导者)。
jmolCommandInput
定义:Jmol.jmolCommandInput(JmolObject, label, size, id, title)
jmolLink
定义:Jmol.jmolLink(JmolObject, script, text, id, title)
script 当用户单击链接时运行脚本。
text 文本作为链接写入页面。如果未指定,则默认为脚本的前 32 个字符。
id 将被设置为 HTML id 和 HTML 名称。它将默认为 jmolLink0、jmolLink1 等。
例子:
Jmol.jmolLink(myJmol,"load adenine.mol","adenine");
title:
此外,链接文本将包含在 <span> 元素中,该元素的 HTML id 为“span_”加上给定的 id,以及给定标题的 HTML 标题。
因此,当鼠标指针停留在链接上时,浏览器会将标题显示为工具提示。
jmolMenu
定义: Jmol.jmolMenu(JmolObject, arrayOfMenuItems, size, id, title)
jmolRadio
定义:Jmol.jmolRadio(JmolObject, script, labelHtml, isChecked, separatorHtml, groupName, id, title)
在页面中插入一个单选按钮,紧随其后的是 labelHtml。
script :当用户选中单选按钮时运行脚本。
labelHtml 被写入单选按钮之后的页面。请注意,它必须是文本字符串(如果您想使用数字,请将其括在引号中)。
isChecked:如果您希望在页面加载时标记单选按钮(默认值:未选中),则应将 isChecked 设置为非 false 值(例如:true)。
groupName:单选按钮将分配给由 groupName 指定的组。换句话说,链接的单选按钮(在选中状态下互斥的)将是那些共享相同 groupName 值的单选按钮。如果您不想使用 groupName,所有按钮将被分配到同一个组(具有自动分配的名称)。
separatorHtml 用于指定应放置在单选按钮及其 labelHtml 之后的 HTML 代码。例如,要将单选按钮放在不同的行上,您应该传入
作为实际参数。如果未指定 separatorHtml,则默认为不间断空格。
id 将被设置为 HTML id。如果未提供,则会自动组成默认名称。
title:单选按钮标签将被
例子:
Jmol.jmolRadio(myJmol,"spacefill 23%; wireframe 0.15;","ball and stick",true);
jmolRadioGroup
定义:Jmol.jmolRadioGroup(JmolObject, arrayOfRadioButtons, separatorHtml, groupName, id, title)
在页面中插入一组互斥的单选按钮。
arrayOfRadioButtons 通常使用 JavaScript 方括号 [ entryA, entryB, … ] 表示法指定。每个条目通常是另一个数组,其中包含一个脚本、一个标签(单选按钮后的页面中显示的文本)和一个可选的 isChecked 标志。如果条目是单个字符串而不是数组,则该字符串用于脚本和标签。
separatorHtml 用于指定应放置在每个单选按钮及其标签之后、下一个单选按钮之前的 HTML 代码。例如,要将单选按钮放在不同的行上,您应该传入
作为实际参数。如果未指定 separatorHtml,则默认为不间断空格。
groupName:单选按钮都属于一个 HTML 名称为 groupName 的组。如果您不指定一个,它将自动组成。
id 整组单选按钮将包含在 元素中,该元素的 HTML id 为 id 的值,如果未给出,则为 groupName 的值。
title:
反过来,每个单选按钮 + 标签将被一个 <span> 元素包围,该元素具有 HTML id span_ 加上组的 id 加上下划线加上序号(从零开始),并且作为其 HTML 标题,公共标题。
每个单选按钮的 HTML id 都是组的 id 加上一个下划线加上一个序号(从零开始)。
每个单选按钮标签将被 <label> 标签包围;效果是单击标签文本将具有与单击单选按钮本身相同的效果。
例子:
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");
Functions that insert HTML -----插入 HTML 的函数
这些简单的命令只是将 HTML 传递到页面。它们只是在正文中使用的便利功能,因此不必不断地进出脚本标签。
同样,所有这些函数都必须应用于唯一的 Jmol 构造函数(这个名称是字面的,不能更改)——请参见下面的语法和示例。
更好的做法是在页面的标题中创建所有控件,从 jQuery 的 $(document).ready() 函数中,使用 Jmol.setDocument(0),使用特定于控件的函数将 HTML 附加到不断增长的字符串,然后使用 jQuery $('#divId').html() 函数在预定义的 div 元素中设置代码。
jmolBr
插入软换行符。它的唯一用途是:
Jmol.jmolBr()
jmolHtml
允许在页面中插入您可能希望的任何 HTML 代码。例子:
Jmol.jmolHtml(' <b style="color:red">H<sub>2</sub>O</b> ')
Functions that set CSS rules----设置 CSS 规则的函数
这些函数在创建关联对象之前调用,允许页面设计者将特定属性(通常,但不一定是 CSS 样式属性)添加到稍后将创建的 HTML 标记。这允许为例如表格的某个单元格中的所有按钮或某个组的所有单选按钮设置一个或多个通用样式属性。可以给出类名或属性。例如:
Jmol.setButtonCss("wideBtn");
<style type="text/css">
.wideBtn { width:220px; }
</style>
Jmol.setButtonCss(null, "style='width:160px'");
同样,所有这些函数都必须应用于唯一的 Jmol 构造函数(这个名称是字面的,不能更改)——请参见下面的语法和示例。
setAppletCss
定义: Jmol.setAppletCss = function(cssClass, text)
setButtonCss
定义: Jmol.setButtonCss = function(cssClass, text)
setCheckboxCss
定义: Jmol.setCheckboxCss = function(cssClass, text)
setLinkCss
定义: Jmol.setLinkCss = function(cssClass, text)
setMenuCss
定义: Jmol.setMenuCss = function(cssClass, text)
setRadioCss
定义: Jmol.setRadioCss = function(cssClass, text)
Functions that interact with a running Jmol Object
与正在运行的 Jmol 对象交互的函数
所有这些函数都必须应用于唯一的 Jmol 构造函数(这个名称是字面的,不能更改)——参见下面的语法和示例。
evaluateVar 评估变量
允许从 Jmol 脚本语言中的变量集、Jmol 数学表达式或某些模型信息中提取到 JavaScript(例如变量)信息。例子:
定义: Jmol.evaluateVar = function(applet,molecularMath)
例子:
alert( Jmol.evaluateVar(myJmol, "a") );
// 如果在 JmolScript 中设置,则显示“a”变量的值。
alert( Jmol.evaluateVar(myJmol, "{*}.xyz") );
// 显示模型几何中心的坐标。
alert( Jmol.evaluateVar(myJmol, "{*}.length") );
alert( Jmol.evaluateVar(myJmol, "{carbon}.bonds.length.min") );
alert( Jmol.evaluateVar(myJmol, "_atomPicked") );
注意:此方法的旧版本 Jmol.evaluate() 已弃用,因为它仅返回字符串、整数或浮点值。
getPropertyAsArray
以 JavaScript 数组(如果适用)或其他适当的 JavaScript 变量类型(如布尔值、数字或字符串)的形式返回小程序信息。
定义: Jmol.getPropertyAsArray = function(JmolObject,sKey,sValue)
例子:
var atoms = Jmol.getPropertyAsArray(myJmol, "atomInfo", "all");
var atom1 = atoms[0];
var x = atom1.x;
var info = atom1.info;
getPropertyAsJavaObject
将属性作为 Java(不是 JavaScript)对象返回。此函数仅供高级用户使用,通常不推荐使用,因为它提供指向 Java 对象本身的指针,而不是它的副本。该指针可能会或可能不会无限期地有效,并且可能会或可能不会被所有浏览器正确地垃圾收集。此函数的主要用途是访问通常无法通过 applet 接口获得的公共查看器方法。
请注意,即使是 HTML5 版本的 JSmol 使用此方法返回的对象实际上都是“Java 对象”。唯一的区别是 JavaScript 实现没有“私有”或“公共”的方面——所有方法实际上都是公共的。
定义: Jmol.getPropertyAsJavaObject = function(JmolObject,sKey,sValue)
例子:
var viewer = Jmol.getPropertyAsJavaObject(myJmol, "jmolViewer")
var radius = viewer.getRotationRadius()
JmolViewer.java 中列出了许多这些公共方法
getPropertyAsJSON
根据 jmolGetPropertyAsArray 返回数据,但始终作为 JavaScript 对象表示法中的 JavaScript 字符串。然后可以将该字符串用括号括起来并进行评估以创建数组内容。或者,可以将 if 转换为具有属性的 JavaScript 对象,如下所述。
定义:Jmol.getPropertyAsJSON = function(JmolObject,sKey,sValue)
例子:
var z = Jmol.getPropertyAsJSON(myJmol, "filename") // {"filename": "file:/C:/data/caffeine.xyz"}
例子:
var z = Jmol.getPropertyAsJSON(myJmol, "filename");
alert( JSON.parse(z).filename ); // 模型文件的 url
var z = Jmol.getPropertyAsJSON(myJmol, "appletInfo");
var d = JSON.parse(z);
alert( d.appletInfo.version ); // e.g. 14.6.2_2016.08.28
alert( d.appletInfo.htmlName ); // JSmol 对象的名称
alert( d.appletInfo.documentBase ); // 包含 JSmol 对象的页面的 url
getPropertyAsString
根据 jmolGetPropertyAsArray 返回数据,但始终作为 JavaScript 字符串。在数组数据的情况下,该字符串被格式化以便于阅读。
定义: Jmol.getPropertyAsString = function(JmolObject,sKey,sValue)
例子:
var s = Jmol.getPropertyAsString(myJmol, 'stateInfo');
img.src = 'data:image/jpeg;base64,' + Jmol.getPropertyAsString(myJmol, 'image');
loadFileFromDialog
Jmol 14.6 中的新功能
打开一个对话框,要求从本地磁盘或 url 加载文件。它可能是模型文件或脚本或数据文件。 (加载操作将异步运行。)
定义:Jmol.loadFileFromDialog = function(JmolObject)
示例(附加到按钮):
<input type="button" value="Load a file" onClick="Jmol.loadFileFromDialog(myJmol)">
或者
Jmol.jmolButton(myJmol, function() { Jmol.loadFileFromDialog(myJmol) }, "Load a file");
script脚本
异步运行 Jmol 脚本,这意味着脚本被放入队列中,并且很可能在函数调用返回之前未处理。该调用可以在小程序创建后的任何时间进行;不必等到小程序准备好接收脚本(就像使用 Jmol.js 时 Jmol/Java 的情况一样)。
定义:Jmol.script = function(JmolObject, myScript)
myScript(包含一个或多个 Jmol 命令的文本字符串)放置在脚本队列中。
例子:
Jmol.script(myJmol, "spacefill off; wireframe 0.3;");
Jmol.script(myJmol, "script someScript.spt;");
scriptEcho脚本回声
同步运行脚本,返回可能已发送到控制台的文本。注意:当使用 JSmol/Java 时,不要直接从回调中调用该方法,因为它可能导致 Java 线程锁,导致整个浏览器挂起。请参阅 scriptWait 下的替代方案。
定义: Jmol.scriptEcho = function(JmolObject, myScript)
例子:
alert(Jmol.scriptEcho(myJmol, "show file"))
scriptWait脚本等待
同步运行脚本,类似于 scriptEcho(),但返回包含消息的字符串。
注意:当使用 JSmol/Java 时,不要直接从回调中调用该方法,因为它可能导致 Java 线程锁,导致整个浏览器挂起。
始终考虑使用 evaluateVar() 而不是 scriptWait。语法:
x = Jmol.evaluateVar(myJmol, "script('background red; print backgroundColor')")
将字符串 [xff0000] 分配给 JavaScript 变量 x。
定义:Jmol.scriptWait = function(JmolObject, myScript)
示例 1:
x = Jmol.scriptWait(myJmol, "background red")
运行该命令并在 JavaScript 变量 x 中返回它:
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]
示例 2:
Jmol.scriptWait(myJmol, "backgroundred")
什么都不做——因为命令不正确,请注意拼写错误——并在 JavaScript 变量 x 中返回:
2,scriptStatus,0,script 15 started
3,scriptStatus,0,script ERROR: command expected
----
>> backgroundred <<
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
如果您仍想从回调中调用 Jmol.scriptWait,请使用以下语法强制 scriptWait 调用位于不同的线程中:
function myCallback(app,param1,param2,....) {
setTimeout(function() {
...your JavaScript callback code here, including Jmol.scriptWait()...
},10);
}