widget中文技术文档

Version 3.1.1 版
2006 年 4 月 14 日
 
著作权 2002-2006 Yahoo! Inc.
保留所有权利
 
版本历史
第一次发行
第二次发行
第三次发行
第四次发行
第五次发行
第六次发行
第七次发行
第八次发行
第九次发行
第十次发行
第十一次发行
第十二次发行
第十三次发行
第十四次发行
第十五次发行
第十六次发行
第十七次发行
 
 
 
 
1.5 版
1.5.1 版
1.6.2 版
1.8 版
1.8.1 版
1.8.3 版
2.1 版
2.1.1 版
3.0 版
3.0.x 版
3.1 版
3.1.1 版
2003 年 2 月 10 日
2003 年 2 月 12 日
2003 年 2 月 15 日
2003 年 2 月 19 日
2003 年 7 月 23 日
2003 年 9 月 26 日
2003 年 10 月 8 日
2004 年 6 月 6 日
2004 年 11 月 8 日
2004 年 11 月 24 日
2005 年 1 月 18 日
2005 年 7 月 23 日
2005 年 8 月 3 日
2005 年 12 月 7 日
2006 年 1 月 6 日
2006 年 3 月 30 日
2006 年 4 月 14 日
 
 
谨在此向所有参与修改和提出宝贵意见的人们致谢。
 
本产品包含由 OpenSSL Project 项目组开发用于 OpenSSL Toolkit 的软件。
(http://www.openssl.org/)
 
 
 
 

Yahoo! Widget Engine 基本介绍
Yahoo! Widget Engine (或简称为 'Widget Engine'，在本文中有时会简称为 'engine') 使用 XML
来定义 Widget工具 (以下在本文中会简称为 ‘Widget’)以及组成它们的对象。这可使对象的层次
更清楚。
 
一个简单的 Widget ：
<widget debug="on">
<window title="Sample Yahoo! Widget">
<name>main_window</name>
<width>500</width>
<height>500</height>
 
<image src="Images/Sun.png" name="sun1">
<hOffset>250</hOffset>
<vOffset>250</vOffset>
<alignment>center</alignment>
</image>
 
<text data="Click Here" size="36" style="bold">
<name>text1</name>
<hOffset>250</hOffset>
<vOffset>100</vOffset> <alignment>center</alignment>
<onMouseUp>
sun1.opacity = (sun1.opacity / 100) * 90;
</onMouseUp>
</text>
</window>
</widget>
 
它所做的事情，就是在用户点击「点击这里」的文字时，将图片透明度降低 10%。这并不是十分
有用的范例，但是我们用这个简单的范例来说明一些重要内容。这个范例需要一个外部文件，即
Images/Sun.png，如果在缺少该文件的情况下执行，将会显示「缺少图片」的符号。
首先，请注意 Widget 的结构：XML 是一种对称式语言，其中每个对象 (例如 <text>) 都有与
之对应的结束标签 (</text>)。如屏幕位置、对齐等对象属性皆可在这些结构组中定义。另请注意，
在 XML 中定义的对象 (例如 sun1) 可以在 JavaScript 中操作 (参见 text1 对象中的 onMouseDown
句柄)。对象名称必须以字母开头，且只允许字母、数字与下划线。Widget 的 XML 会以后缀名为 .kon
的文件存放 (关于此文件所在包的讨论信息，请参见以下信息)。
实际的 Widget 可以含有许多图片与文字、多个 JavaScript 区段 (通常在外部文件中)，而且可
以在运行过程中建立新对象，并使用 JavaScript 来实现复杂的功能。
显然，制作 Yahoo! Widget 的最轻松的方法就是获得现有的 Widget，并对其进行修改。
 
 
基础
我们有功能强大的 XML 解析器，这表示可以使用标签批注样式或混合搭配样式。这两种样式是：
<image>

<src>images/image.png</src>
<name>myImage</name>
</image>
 
或：
<image src="images/image.png" name="myImage"/>
 
混合搭配也不错：
<image src="images/image.png">
<name>myImage</name>
</image>
 
实体
实体是通过特殊字符序列来代表另一个字符的 XML 结构。
&amp;
&
&quot;
"
&apos:
'
&lt
<
&gt
>
 
也可以依照其 unicode 字码，使用实体来指定字符：
&#32; <space character, decimal>
&#x20; <space character, hex>
这些实体只能在 2.1 版或更高版本中使用。XML 引擎会寻找 < 和 > 符号以标记 XML 数据的标
签，我们的 JavaScript 引擎需要以 &lt; 和 &gt; 来分别取代这些符号。例如：
<onMouseUp>
if (x &lt; 5)
displayResults();
</onMouseUp>
也可以采用 HTML 中的作法，使用 XML 批注来对 XML 引擎隐藏 JavaScript 程序代码，如下所
示：
<onMouseUp>
<!—
 if (x < 5)
 displayResults();
//-->
</onMouseUp>
 
这是惯用的作法，因为它可以让程序代码更清晰可读。
在 2.1 版或更高版本中，可以使用 CDATA 区段：
<onMouseUp>
<![CDATA[
if (x < 5)

displayResults();
]]>
</onMouseUp>
 
也可以应用外部 JavaScript，我们稍后将会介绍这个部分。
 
严格模式 (Strict Mode)
在 2.1 版或更高版本中，可以将 XML 解析器设定为「严格」模式。这表示它将会采用某些过去
未曾使用的方式来强制执行 XML 规则。实际上，它在许多方面都不是很严格的。要启用此模式，只需
将以下这一行加到 XML 文件的上方即可：
 
<?konfabulator xml-strict="true"?>
 
在严格模式下，将会强制执行以下操作：
1) 所有的属性值都必须加上引号。
2) 文字区段中不允许使用单独的 "&" 字符 (只能是这样的形式 &amp;)。
3) 实体 (以 "&" 开头的字符串) 的属性值会被评估。
4) 批注中不允许使用双横线 ("--")。因此最好将程序代码放进 CDATA 标签中。
5) 如果包含了外部文件，不会在该文件中替代 &lt; 等实体。
CDATA 标签适用于 2.1 版或更高版本。
 
文件路径 (File Paths)
引擎中的文件路径总是与 XML 文件的位置相关。这表示未指定目录的文件 (例如 main.js) 在
XML 文件所在的目录中寻找，而指定了目录的文件 (例如 javascript/main.js) 在 XML 文件所在目
录的子目录中寻找。不建议使用绝对路径 (以 / 开头的路径)，因为用户机器的磁盘配置可能会有明
显的差异。
 
Widget 封装 (Widget Packaging)
在 Windows 上，组成 Widget 的文件存放在 .widget 文件中。这是一个已经将其后缀名改
为 .widget 的标准 ZIP 文件。
无论在 Windows 上或是在 Mac OS X 上，.widget 包皆有以下结构：
myWidget.widget
Contents
myWidget.kon
Resources
<any files used by the Widget">

.kon 文件包含 Widget 的程序代码 (与以上部分中的范例 Widget 相似)。目前 .kon 文件必须
包含在被称为 Contents 的文件夹中。可以将图片等资源放到任何地方，但是它们通常会被放到
Resources 文件夹中，如上所示。
如果不使用 Widget converter 封装 Widget，而是手动压缩它们，在 PC 上最好的操作方式是
在 .widget 文件夹上点击鼠标右键，选择从该处建立 ZIP 文件。在 Mac 上，可以使用例如 DropZip
之类的程序。
请注意，开发 Widget 时，不需要在每次进行改变时都建立新的 Widget 压缩包，只需要双击 .kon
文件即可。
不可以在执行期间修改 Widget 。也就是说，请勿将信息存放在 Widget 自身中。虽然大多数
Widget 都使用偏好设置来存放它们的设定值，但是仍然有一些 Widget 将信息存放在它自身中。当
Widget Engine 执行压缩的 Widget 时，它首先会将其解压缩到一个特定的位置，然后从该处执行它。
在最近的版本中，这个解压缩的动作会在每次执行 Widget 时进行，因此，如果将信息存放在 Widget
中，就会丢失该信息。存放永久性数据可以使用 system.widgetDataFolder。
 
Flat-File 封装格式 (Flat-File Format)
从 3.1 版开始，引擎支持非 zip 的 flat-file 格式。zip 解决方案不仅有性能方面的问题 (特
别是在 3.0 中)，还会产生其它一些麻烦。
现在，新格式的 Widget并不被压缩，因此 Widget 的大小在这种格式之下会比 zip 格式要大。
但是，由于图片占据了 Widget 绝大部分的大小，增加的大小平均约为 10-15%，因为图片通常已是压
缩格式 (PNG、JPG)，而文本则不然。文件不会刻意压缩，这样就可以对文件进行文件映射，在真正需
要用到之前，不需要将所有内容加载进内存 。
由于有了这种新格式，Widgets 3.1 的启动速度比 3.0 要快多了。要使用这种新格式，必须用到
Widget Converter。
对于 flatfile 格式，除非使用新的 API (widget.extractFile()) 来将文件从 flat-file Widget
中释放到文件系统中，否则将无法使用 dll 等随 Widget 一起封装的项目。但是，通过 play() 函数
播放的声音文件仍可正常使用。
Widget Runtime
将Widget 做为独立的程序运行，这可以确保一个 Widget 出问题时不会影响到其它 Widget。
压缩的 Widget 将会解压缩至特定位置 (Mac 上为 /tmp，PC 上为 C:/Documents and
Settings/<user>/Local Settings/Application Data)。未压缩的 Widget 则会直接在其所在位置上
执行。当我们在 Widget 中找到 .kon 文件时，可以将当前目录设定为找到 .kon 文件的目录。举例
来说，如果 .kon 文件如同往常般在 Contents 文件夹中，当前的工作目录就是 Contents，这样相
对路径才可以正确使用。如果 .kon 文件的图片位于 Contents 底下的 Resources 文件夹中，.kon 文
件便可以像这样应用图片 Resources/Image1.png。
找到 .kon 文件，且当前工作目录也设定好了之后，文件会被解析，并且建立程序中定义的对象。
所有项目都成功建立好了之后会调用 onLoad 句柄 (参见 'action' 对象说明文件)。此时， Widget 便
可以进行初始化了。成功执行了 onLoad 之后， Widget 便开始执行了！
Widget 将会在下一次执行时再次解压缩。因此你无法在 Widget 包中存放信息，请将需要存储的
信息放至的 widgetDataFolder。
Widget Engine 将自动记录打开了哪些 Widget。下一次启动引擎时，它将会重新打开上一次结束

时正在运行的 Widget。
动作 (Actions)
动作是 Widget 的命脉。它定义用户与 Widget 交互的情况下，Widget 将做些什么。在 3.0 版
之前的版本中，指定动作的唯一方法是将动作设定为某些 Javascript 代码，这些代码会在用户点击
鼠标左键时被检查，执行，例如：
<onMouseUp>
print( "hello" );
</onMouseUp>
 
有如下限制
a) 不可以使用 Javascript 的 'this' 来引用当前的对象
b) 如果有数个含有相同代码的对象，必须改变对象名称，以区分程序代码的每个对象。
为了修正此类情况，在 3.0 版或更高版本中，引擎支持在动作中调用Javascript 函数。在 3.0
版中，不可以把参数传给动作，但在未来的版本中应该支持传送参数。例如，onMouseUp 句柄接收鼠
标的 x 与 y 坐标，而不用再检查 system.event。
可以使用属性 (而且必须是属性，不能用子元素)，或在 Javascript 中设定要调用的函数的属性
来告知引擎你想要调用的函数：
 
<!-- In XML -->
<onMouseUp function="_myMouseUp"/>
// 在 Javascript 中
myImage.onMouseUp = _myMouseUp;
// 在你 JS 程序代码的某处，必须定义函数：
function _myMouseUp()
{
print( this.opacity );
}
对象名称 (Object Names)
可以在 XML 描述中设定 <name> 属性。 这将会定义全局 Javascript 对象，它将被并绑定至名
称为其前缀名的对象。例如：
<window name="mainWindow" .../>
因为这些名称是在内部用来跟踪对象的，因此不应改变，3.0 版将所有名称属性强制为只读来达
到此目的。
调试 (Debugging)
当设定debug标签为 “on ”时，调试窗口会在运行 Widget 时显示。在 JavaScript 程序代码

中调用 log() 或 print() 将会把调试信息传送至此窗口。Widget Engine 或 Widget 中所发生的任
何错误也将会在此窗口中显示。
开发 Widget 时，应该始终将调试功能打开，以便使了解到可能发生的错误。例如，如果将某个
属性拼错了，调试窗口将会显示错误，并给出程序代码中出现问题的位置。
请注意，特别是在 PC 上，除非将调试设定为打开，否则调试窗口将永远不会打开。
在 2.1 版及更高版本中，可以按住 control 与 shift 按键，然后在菜单中选择「工具」菜单来
打开调试模式。当选择此选项之后，启动的任何 Widget 都将会强制打开调试窗口。因此，不需要再
在 Widget 中使用调试标签。也可以让用户使用此模式来诊断问题的所在。
 
另外在 2.1 版或更高版本中，调试功能已通过新的命令行字段来增强。可以在此字段中发出命令
(在字段中键入 "/help" 来显示完整的清单) 或只是简单评估一些 JavaScript。这对于检查变量值等
工作是很方便的，也可以使用内置命令来跟踪变量与函数。
 
异常 (Exceptions)
从 2.0 版开始，Widget Engine 会在发生错误时产生异常。了解并在适当的地方使用 try/catch
句柄非常重要，这对于 COM 是必须的，它可以帮你摆脱并处理联机失败等情形。Day Planner Widget
将会在其 Outlook 处理中使用 try/catch。
Widget 偏好设置 (Widget Preferences)
Widget 提供一些存放设定值的对象。这些设定值存放在每个用户的偏好设置区域中。在 Mac 上，
此设定值位于 ~/ Library/Preferences/Konfabulator 中。在 PC 上，此设定值位于
HKEY_CURRENT_USER/ Software/Yahoo/WidgetEngine 中。
最低版本需求 (MinimumVersion)
<widget> 的最低版本属性会通知引擎哪个版本的引擎才能执行该 Widget。但是从 3.0 版开始，
它也会通知引擎此 Widget 已针对 3.0 版进行修订，而就其本身而言，我们将可以使用它来改变
Widget的某些行为。
如果将最低版本需求设定为 3.0，应注意以下事项：
1) 视图不会自动绑定至默认窗口。以前情况或许是如此，但是随着 3.0 版中层次视图的出现，
这将会出问题，必须指定对象所属的窗口，或使用 frame.addSubview() 来将对象内嵌至框体中。如
果接口大部分由 XML 结构实现，那么你只需要将 image/text/frame/scrollbar/textarea 对象置于
窗口对象中即可：
<window ...>
<image src=.../>
<text data=.../>
<frame .../>
<image src=.../>
</frame>

</window>
将 Widget 升级到 3.0 版时可能会发生的最常见错误就是一些视图没有显示出来。这都是因为这
个行为的改变所造成的。你只需反复检查所有的视图是否皆已绑定至某些窗口或父框体即可。
 
2) Javascript 有效生存期的改变。在之前的版本中，调用对象上的删除或将它设定为空将会使
对象从窗口中消失。而现在如果要移除对象，必须调用 <object>.removeFromSuperview()。此改变使
得编写 Widget 更加简单。过去必须维持所有对象的清单才可以确保它们不会跟着窗口一起消失。随
着子视图的出现，对象数目将会很快地变得非常的多。现在，不需要跟踪在 Widget 的运作过程中永
远不会改变的项目，这将使 程序代码更加清晰可读，而你只需集中精力做好你最擅长的工作即可。
 
3) 当载入文件时，引擎不再盲目替代 .kon 或 .js 文件中的 XML 实体。如果要确保内含 < 或
> 的 Javascript 程序代码不会使解析器发生解析错误，应该使用之前提到过的 CDATA 标签。
 
4) 旋转的改变。现在我们可以让对象进行垂直与水平的旋转了，这表示如果使用 hAlign 与
vAlign 来置中图片，然后旋转它，它将会围绕图片中心旋转。
 
5) XML 元素中的 Javascript 程序代码将只会做为 Javascript 程序代码来读取。之前，引擎会
尝试读取指定路径的文件来看看它是不是文件。如果动作有 'file' 属性，引擎会尝试读取文件。如
果要包含文件，请使用 include()。
 
XML 服务 (XML Services)
从 3.0 版开始，我们已经提供新的服务，帮助你更轻松地使用 XML。在 3.0 版中，我们拥有内
置 XML 解析器，这个 XML 解析器一定是在「严格」模式下作工作(参见以上严格模式的注意事项)。
解析器的输出是 Level 1 W3C DOM，我们严格依照上述 DOM 的 RFC 操作。也可以建立并改变这
些 DOM 树形结构，建立你自己的 XML 文件并输出它们。
 
DOM API 还不错，但是在一般情况下，要来回传送 XML 树形结构不是非常方便。因此我们新增了
XPath 1.0 支持 (不含 namespacespecific
函数)。这个支持会使从 XML 树形结构中取出项目比使
用 DOM API 更简单。
Yahoo! 服务账号登陆支持
3.0 版以及更高版本允许使用需要 Yahoo!账号的 API。引擎将会处理登陆并存放证书的详细信
息。 Widget 只需要检查目前登陆状态或要求登陆即可。登陆之后，当 API 将要求传送至服务器时，
引擎将自动为你新增用户证书。
注意：在 3.1 版及更高版本中，必须在 <security> 标签中指定 Widget 所要连接的正确的Yahoo!
API (关于更进一步信息，请参考 XML 参考中的安全性标签的说明)。在允许 Widget 使用 Yahoo! 证
书之前，这份 API 清单要由用户确认，且只有那些 API 才能收到 Yahoo! 证书。如果使用的是 3.1 之
前的 yahooLogin()， Widget 将无法再存取那些 API，除非经过修改后包含安全标签。
你应该首先调用 yahooCheckLogin() 以察看你是否已经登陆。如果返回了 true，即表示你已经
登陆；如果返回 false，你应该提供一条提示信息，表明目前用户还没有登陆，并提供一个可以点击
的按钮/连结/或其它项目，来让用户从 Widget 中登陆。

举例来说：
if ( yahooCheckLogin() ) loggedIn(); // 在登陆状态下显示 UI。
else
loggedOut(); // 在注销状态下显示 UI。
盲目地在 onLoad 句柄中调用 yahooLogin() 是很不好的。
当用户点击按钮来登陆时，请调用 yahooLogin()。如果此函数返回 true，即表示你已经登陆了。
当 yahooLogin() 返回 false 时，你只需要忙你自己的事情，等待 onYahooLoginChanged 事件的来
到(亦即，函数将会异步执行)。如果用户从「工具」菜单中登陆或注销，也会调用 onYahooLoginChanged
句柄。
 
当 onYahooLoginChanged 句柄被调用时，必须调用 yahooCheckLogin() 查看 新状态 (此调用
也会加载必要的 cookie 等)。根据返回的状态进行登陆或注销。
请注意，即使 yahooCheckLogin() 返回 true，你对 API 服务器的请求也可能因为证书过期而失
败。在这种情况下， Widget 应调用 yahooLogout()，以便其它 Widget 也可收到该情况的通报。
子视图/框体 (Subviews/Frames)
从 3.0 版开始，Widget Engine 现在已经可以支持层次型视图了。在 3.0 版本之前，你只能拥
有窗口中对象 (图片、文字等) 的一般清单。3.0 版中出现了「框体」对象，它可以让将对象加到其
中，并将它做为一组项目来处理。如果你移动「框体」，子视图也会随着它移动。如果你淡入/出框体，
框体中的所有项目皆会跟着淡入/出。
将对象放置于框体中时，它的 hOffset 与 vOffset 将会变成与框体相关。基本上位移总是与视
图所属对象相关。因此 h/ vOffset 为 10, 10 的图片将会向下显示 10 个像素，并位于其父框体左
上角，你完全不必担心它在窗口中的位置。
即使是在窗口最上层不在任何框体中的对象，也真实存在于窗口的根视图中。可以通过窗口对象
来存取此根视图。根视图是一种特殊视图，它只包含让你成功来回传送视图所必需的属性与函数。
「框体」还具有滚动其内容的能力。这将可以让你建立搜寻结果与其它各种项目的滚动清单。
Widget Engine提供标准的 ScrollBar 对象，可以将其附加至「框体」以滚动其内容。当滚动条绑定
到框体时，鼠标滚轮支持将自动启用。ScrollBar 对象可以为其标准滚动方块上色，如果不符合 需要，
也可以为轨道与滚动方块提供你自己的图片。
安全警告窗口 (Security Windows)
Widget Engine 中可以显示两种安全警告窗口，但它们看起来非常相似。第一个是首次执行/修改
窗口。当首次执行引擎不熟悉的 Widget 时，会显示一个窗口，通知用户将要打开新的 Widget，并让
他们确认，这可以避免用户在不了解的情况下执行 Widget。另外，如果用户允许 Widget 执行，但是
稍后 Widget 受到了修改，另一个提示窗口将会于下次 Widget 启动时显示，并将此情况通知用户。
需要频繁调试 Widget时，可以打开调试模式 (可能是一个很好的主意)，首次执行/已修改的安
全警告窗口将不再出现，不会在你每次调整程序及重载 Widget 时打扰你。
第二种窗口是 'sandbox' 窗口。目前，唯一经过沙盒的操作就是登陆用户的 Yahoo! 账号 (更多
操作将会在未来的版本中使用沙盒)。当 Widget 第一次尝试登陆用户的 Yahoo! 账号时，窗口将会显
示出来，以向用户通知这个情况，并询问是否应授予 Widget 使用其 Yahoo! 账号的权限。Sandbox 窗
口无法停用。

本地化 (Localized Widgets)
在 3.1 版或更高版本中可以编写出能在多种语言环境之下正确显示的 Widget 。为了达到这个目
的，需要在 'Resources' 文件夹底下建立适当的目录。这些目录中含有称为 Localizable.strings 的
文件，是内嵌字符串文件。例如：
"save_as_button" = "Save As";
请注意，等号的两边都必须在引号中，每一行都必须以分号结尾。
你放置这些文件的目录必须通过 ISO 语言码来命名，也可以选择通过 ISO 地区码来命名。在这
个文件夹中必须有名为 Localizable.strings 的特殊格式文件。例如：
英文，所有地区：
Resources/en/Localizable.strings
英文，美国地区：
Resources/en_US/Localizable.strings
为了寻找正确的字符串文件，引擎会先搜寻 <lang>_<locale>，然后搜寻 <lang>。如果在两处都
找不到，则依默认加载 'en'。使用的语言/地区是由引擎的「偏好设置」对话框中的「语言」来设定
的。这个语言设定只影响在完成设定之后所执行的 Widgets。在众多设定值中有一项是系统默认值，
即操作系统所使用的语言。
引擎提供了一个新函数用于寻找本地语言：
widget.getLocalizedString()，参见本节稍后的 widget.locale
 
XML 参考
以下章节描述组成 Widget 的对象及其属性。
<widget>
<about-box/>
<action/>
<frame/>
<hotkey/>
<image/>
<preference/>
<security/>
<scrollbar/>
<text/>
<textarea/>
<window/>
</widget>
其它为子标签的标签：
<menuItem/>
<shadow/>
 
从 2.1 版开始，可以将对象以层次结构置于窗口之中。这表示可以将图片、文字以及 textarea 这
些对象置于窗口标签中：
<window>
 ...
<image name="foo"/>

 <text .../>
</window>
使用这种方法，不需要为层次结构中的图片指明窗口属性，因为这个窗口就是 XML 中指定的内含
窗口。如果你指定了窗口，将会在调试窗口中看到错误信息。
 
<about-box> ‘关于窗口’定义图片的标签
属性 (Attributes):
image/about-image
about-text
about-version
 
image/about-image 包含图片路径的标签
“关于”标签的图片属性必须包含图片的有效路径。如果已使用一个以上的图片属性，图片将会
连续显示给用户。当它们的大小都相同时，它们将会简单地互相取代，当它们的大小不同时，第一个
图片将会先淡出，然后下一个图片会淡入。
 
范例:
<about-box>
<image>Resources/About.png</image>
<image>Resources/Thanks.png</image>
</about-box>
about-text 显示的文字
可以指定在关于窗口中显示的任意数目的文字,目前这些文字只会显示在关于窗口的第一页上。它
们有以下属性：
color/colour
data
hOffset
font
size
style
shadow
url
vOffset
 
url 属性可将文字变成超链接，它会打开浏览器并链接到你所指定的 url。
 
可用性
适用于 2.1 版或更高版本。url 属性适用于 3.0 或更高版本。

 
 
 
about-version 版本号
实际上这是文字的特殊情况，在上面的内容中已有所描述。它拥有文字的所有属性，只能放置于
关于窗口的第一页上。最大区别是这个标签代表了 Widget 的版本号显示的位置。版本号可以从
Widget 标签中定义的 version 属性中取得。
可用性
适用于 2.1 版或更高版本。
 
 
<action> 与对象没有关联的程序代码标签
属性：
file
interval
trigger
action 标签可定义 Widget 执行程序代码的时间与方式，它是自动触发的，而非由用户触发。
File 外部 JavaScript 文件的路径
将 JavaScript 程序代码内嵌至 XML 文件中可能会给某些开发人员带来一些特殊问题。你偏好的
文字编辑器可能无法同时支持 XML 与 JavaScript 语法， JavaScript 程序代码可能会比较大，而
且比较复杂，因此需要更好的管理。为了解决这些问题，允许应用外部文件。
可以为 <action> 标签指定 file 属性来应用文件，也可以使用 include()。
范例：
<action trigger="onLoad" file="main.js"/>
<action trigger="onLoad">
include( "main.js" );
</action>
 
interval 在触发之间等待的秒数
action 标签的 interval 属性可与 onTimer trigger 属性搭配使用。它定义了在执行 onTimer 程
序代码之间等待的秒数。
如果没有定义打触发定时器的间隔，默认为一分钟。
 
范例：

<!-- 这将会使 Widget 每两分钟响一次哔声 -->
<action trigger="onTimer" interval="120">
beep();
</action>
<!-- 这将会使计数器每秒钟增加十次 -->
<action trigger="onTimer" interval="0.1">
counter ++;
</action>
从 2.0 版开始，此机制就已经由新的 Timer 对象所取代 (请参见本手册稍后的 Timers 一节说
明)。
trigger 触发程序代码的事件
属性：
onGainFocus
onIdle
onKeyDown
onKeyUp
onKonsposeActivated
onKonsposeDeactivated
onLoad
onLoseFocus
onMouseDown
onMouseEnter
onMouseExit
onMouseUp
onPreferencesChanged
onRunCommandInBgComplete
onScreenChanged
onTellWidget
onTimer
onUnload
onWakeFromSleep
onWillChangePreferences
onYahooLoginChanged
 
说明：
trigger 定义了将要触发程序代码的动作。
 
当用户激活 Widget 时，onGainFocus 将会触发。在 2.0 版与更高版本中，通常应在每个窗口上
都使用 onGainFocus 句柄，而保留 Widget onGainFocus 句柄以用于 Widget 的启动处理。
 
onIdle 一秒钟可以执行 5 次，但不建议使用它，因为它会占用过多的 CPU 时间。
 
当用户设置或取消智能显示模式时，onKonsposeActivated 与 onKonsposeDeactivated 将被触
发。Widget 可以在这个时候改变显示模式或进行其它的操作。

 
当第一次载入 Widget时，onLoad将被触发。
 
当用户关闭 Widget 时，onLoseFocus 将会触发。在 2.0 版与更高版本中，通常你应在每个窗口
上都使用 onLoseFocus 句柄，并保留 Widget onLoseFocus 句柄以用于 Widget的启动处理。
 
当用户改变偏好设置时，便被触发 onPreferencesChanged。请注意，如果用户取消偏好设置对话
框，将不会执行任何操作，因为这种情况下并未改变偏好设置。
 
当进行 runCommandInBg() 调用之后，将会触发 onRunCommandInBgComplete。
 
如果使用「显示系统偏好设置」面板改变了屏幕大小，排列或色彩深度，onScreenChanged 将会
触发 (请注意，Widget 本身所在的屏幕可能受到影响，也可能不会)。
 
当其它 Widget 或应用程序调用了 tellWidget 接口来传送Widget 信息时，便会触发
onTellWidget。对于如何处理接收到的信息应特别小心。关于更进一步的信息，请参见本文件稍后的
tellWidget 一节说明。此触发器适用于 Widget Engine 2.0 版或更高版本。
 
onTimer 会根据在 interval 属性中的定义以固定的间隔执行。如果未定义 interval 属性，将
会默认为一分钟间隔。请注意，每个 Widget 只能有一个 onTimer 触发器。因此，在 2.0 版与更高
版本中，我们提供了新的 Timer 对象，它可让有多个以不同频率执行的定时器。关于更进一步信息，
请参见有关 Timer 的小节说明。
 
当 Widget 关闭时，onUnload 便被触发。对于手动偏好设置的保存 (当用户改变偏好设置时，在
Widget「偏好设置」对话框中所做的偏好设置便会自动存放)，以及是否关闭正在交互的外部应用程序
来说，这是很有用的。
请注意，不应该在此触发器中执行冗长的作业，因为 Widget 很快便会关闭 (例如，从网络中获
取内容)。
 
当机器从睡眠状态恢复时，onWakeFromSleep 便被触发。应该注意的是，某些桌面计算机在醒来
与重新联网的过程间会有几秒钟的延迟，因此，如果 Widget 要联机至因特网，可能需要将 sleep()
调用加到程序代码中。在 3.0 版或更高版本中，当机器进入睡眠时，定时器便会停止，且在调用
onWakeFromSleep 之前，不会重新启动。
 
当用户编辑 Widget 的偏好设置时 (或当进行 showWidgetPreferences() JavaScript 调用时)，
onWillChangePreferences 便被触发。
 
当用户登陆或注销他们的 Yahoo! 账号时，onYahooLoginChanged 便被触发。之后，可以调用
yahooCheckLogin() 来检查用户目前的登陆状态。
 
当Widget 主窗口中侦测到相应的用户动作，且没有其它对象接收时，剩余的触发器――
onKeyDown、onKeyUp、onMouseDown、onMouseUp、onMouseEnter 与 onMouseExit 便被触发。请注意，
使用全局范围的鼠标动作将会使 Widget 在不按住命令键的情况下无法进行拖曳。
 
范例：
<!— 从睡眠中被唤醒时，重绘时钟 -->
<action trigger="onWakeFromSleep">

 updateClockFace();
</action>
<!— 当用户改变偏好设置时，更新我们的信息 -->
<action trigger="onPreferencesChanged">
refreshTickerSymbols();
</action> <frame>
 
<frame> 框体
框体对象可作为其它对象的容器。可以在 XML 中将其它对象置于框体之内，也可以使用
Javascript 来将其它对象放到框体之内。框体移动之后，所有子视图也会移动。同样地，当框体的透
明度改变时，其中每个项目的有效透明度也都会改变。
 
框体允许滚动。可以调整 scrollX 与 scrollY 来手动滚动，也可以将滚动条连接到框体上，然
后所有的动作自动完成。
 
属性：
contextMenuItems
hAlign
height
hLineSize
hOffset
onContextMenu
onDragDrop
onDragEnter
onDragExit
onMouseDown
onMouseEnter
onMouseExit
onMouseMove
onMouseUp
onMouseWheel
onMultiClick
opacity
scrollX
scrollY
visible
vAlign
vLineSize
vOffset
width
window
zOrder

 
contextMenuItems 指定菜单项目的数组。
可以将项目加到用户在框体上点击鼠标右键时所弹出的菜单中。可以在 onContextMenu 标签上执
行某些 JavaScript 来动态地建立 菜单项目 (关于更进一步信息，请参见 onContextMenu)。
可以包含 menuItem 对象数组来指定 项目。（关于更进一步信息，请参见有关 menuItem 的小节
说明）
 
JavaScript
myObjectName.contextMenuItems
 
范例
<frame>
...
<contextMenuItems>
 <menuItem title="Test" onSelect="beep();"/>
<menuItem title="Another Test">
<onSelect>alert( 'hello' );</onSelect>
</menuItem>
</contextMenuItems>
</frame>
请参见 onContextMenu 小节中有关在 JavaScript 中建立菜单的范例。
 
适用性：
适用于 3.0 版或更高版本。
 
hAlign 控制框体的水平对齐
说明：
hAlign 属性可以定义与 hOffset 属性有关的初始水平对齐方式。例如，显示 right 对齐的对象，
以使其右边缘能够显示在 hOffset 上。默认对齐方式为 "left"。
对齐方式包括："left"、"right" 或 "center"。
 
JavaScript
myObjectName.hAlign
 
范例
<frame>
<hAlign>right</hAlign>
</frame>
myFrame.hAlign = "left";
 
适用性：
适用于 3.0 版或更高版本。

 
height 对象的高度
说明：
height 属性控制对象的垂直尺寸。如果未指定框体高度，其高度将由其子视图自动决定。
 
JavaScript
myObjectName.height
 
范例
<frame>
<height>300</height>
</frame>
myFrame.height = 300;
 
适用性：
适用于 3.0 版或更高版本。
 
hLineSize 滚动时数据行的大小
说明：
hLineSize 属性指定了如果调用 lineLeft() 或 lineRight() 函数时，框体应该滚动的距离 (像
素)。当框体对鼠标滚轮做出响应时 (如果已连接滚动条)，则也将它列为重要因素。默认的行大小为 10
个像素。
JavaScript
myObjectName.hLineSize
 
范例
<frame>
<hLineSize>5</hLineSize>
</frame>
myFrame.hLineSize = 5;
 
适用性：
适用于 3.0 版或更高版本。
 
hOffset 对象的水平位移
说明
hOffset 属性以父视图左上角（0.0）为基点为对象定义水平 (从左到右) 的位移。数值越大，对
象就越往右显示。
 

JavaScript
myObjectName.hOffset
 
范例
<frame>
<hOffset>30</hOffset>
</frame>
 
适用性：
适用于 3.0 版或更高版本。
 
 
hScrollBar 水平滚动条
说明
hScrollBar 属性定义控制此框体水平滚动的滚动条对象。以 XML 表示时，可以指定要绑定至其
hScrollBar 框体的 <scrollbar> 对象名称。如果滚动条对象不存在，Widget 调试窗口中将会显示错
误信息。
附加滚动条将会自动设定以便在框体与滚动条之间进行通讯。
 
JavaScript
myObjectName.hScrollBar
 
范例
<frame>
<hScrollBar>my_scrollbar</hScrollBar>
</frame>
<scrollbar name="my_scrollbar" ... />
// 在 Javascript 中：
myFrame.hScrollBar = my_scrollbar;
 
适用性：
适用于 3.0 版或更高版本。
 
onContextMenu 显示菜单时调用
说明
为 Widget 指定加到标准菜单中的菜单项目，最简单的方法就是在 XML 中使用 contextMenuItems
标签。但是，对于那些需要动态建立项目的 Widget 来说，onContextMenu 句柄是最好的工具。将要
显示菜单时，在某些视图响应之前，它会按照视图顺序从前到后调用所有元素。处理此情况时，只须
建立菜单项目，并将contextMenuItems 属性设定为项目数组即可。
 
JavaScript
myFrame.onContextMenu

 
范例
<onContextMenu>
var items = new Array();
items[0] = new MenuItem();
items[0].title = "This is the title";
items[0].enabled = false;
items[0].checked = true;
items[0].onSelect = "alert( 'you chose it!' );";
items[1] = new MenuItem();
items[1].title = "This is the second title";
items[1].onSelect = "beep();";
myFrame.contextMenuItems = items;
</onContextMenu>
适用性：
适用于 3.0 版或更高版本。
 
 
onDragDrop 将某些项目放到对象上时调用
说明
将文件、URL 或字符串从其它应用程序中拖曳出来并放到 Widget 对象上时，onDragDrop 触发器
便会触发。
在 onDragDrop 中，对象可以读取 system.event.data 来查看拖放的内容。这是字符串数组，它
的第一个元素指定了拖放对象的类型："filenames"、"urls" 或 "string"。剩余元素就是被拖放的项
目。
 
JavaScript
myObjectName.onDragDrop
 
范例
<frame>
<onDragDrop>
 if (system.event.data[0] == "filenames")
 {
processDroppedFiles(system.event.data);
}
</onDragDrop>
</frame>
myFrame.onDragDrop = "handleDragDrop();";
 
适用性：
适用于 3.0 版或更高版本。
 

onDragEnter 将项目拖曳到对象中时调用
说明
onDragEnter 属性是当用户已将项目从其它应用程序中拖曳到对象中时将被调用的 JavaScript
函数。这可以用来触发对象的外观发生变化，以指示用户拖放对象是否被拒绝。有关拖曳项目的信息，
可查阅 system.event.data (如需详细信息，请参见 onDragDrop)。
 
JavaScript
myObjectName.onDragEnter
 
范例
<frame>
<onDragEnter>
 highlightDropTarget(well);
</onDragEnter>
</frame>
well.onDragEnter = "highlightDropTarget(well);";
 
可用性
适用于 3.0 版或更高版本。
 
onDragExit 将项目拖曳到对象外时调用
说明
onDragExit 属性是当用户已将项目从其它应用程序中拖曳到对象中然后再拖出去时将被调用的
JavaScript 函数。对于取消已在 onDragEnter 中执行的项目来说，这是很有用的。
 
JavaScript
myObjectName.onDragExit
 
范例
<frame>
<onDragExit>
unhighlightDropTarget(well);
</onDragExit>
</frame>
well.onDragExit = "unhighlightDropTarget();";
 
可用性
适用于 3.0 版或更高版本。
 

onMouseDown在对象上按下鼠标按键时调用
说明
onMouseDown 属性指定了当用户在对象上按下鼠标按键时将要执行的 JavaScript 程序代码。
 
JavaScript
myObjectName.onMouseDown
 
范例
<frame>
<onMouseDown>
beep();
</onMouseDown>
</frame>
myFrame.onMouseDown = "beep();";
 
可用性
适用于 3.0 版或更高版本。
 
onMouseEnter 当鼠标进入对象时调用
说明
onMouseEnter 属性指定了当用户将光标移动到对象上时将要执行的 JavaScript 程序代码。
对于根据滚动状态触发对象的外观发生变化来说，这是很有用的。
 
JavaScript
myObjectName.onMouseEnter
 
范例
<frame>
<onMouseEnter>
print( "Mouse entered!" );
</onMouseEnter>
</frame>
myFrame.onMouseEnter = "handleEntered();";
 
可用性
适用于 3.0 版或更高版本。
 
onMouseExit 当鼠标离开对象时调用
说明
onMouseExit 属性指定了当用户将光标从对象中移动到对象外时将要执行的 JavaScript 程序代

码。对于根据滚动状态触发对象的外观发生变化来说，这是很有用的。
 
JavaScript
myObjectName.onMouseExit
 
范例
<frame>
<onMouseExit>
print( "Sadly, the mouse has left us." );
</onMouseExit>
</frame>
myFrame.onMouseExit = "handleMouseExit();";
 
可用性
适用于 3.0 版或更高版本。
 
onMouseMove 当鼠标在对象中移动且按下鼠标时调用
说明
onMouseMove 属性指定了当用户将鼠标光标移动到对象所在的范围内时要执行的 JavaScript 程
序代码。目前的鼠标位置可以在 system.event 对象中使用。
 
JavaScript
myObjectName.onMouseMove
 
范例
<frame>
<onMouseMove>
print(system.event.x + ", " + system.event.y);
</onMouseMove>
</frame>
myFrame.onMouseMove = "handleMouseMove();";
 
可用性
适用于 3.0 版或更高版本。
 
onMouseUp 在对象上放开鼠标按键时调用
说明
onMouseUp 属性指定了当用户在对象中按下鼠标按键再放开它时，将要执行的 JavaScript 程序
代码。
对于根据按下的状态触发对象的外观发生变化来说，这是很有用的。
请注意，即使放开鼠标按键时鼠标不在对象内，onMouseUp 也会触发。建立处理鼠标事件的按钮
必须使用所有四个鼠标事件句柄，以传送鼠标的状态及其交集状态 (关于此项目的范例，请参见随附

的 Calendar Widget)。
 
JavaScript
myObjectName.onMouseUp
 
范例
<frame>
<onMouseUp>
handleOnMouseUp();
</onMouseUp>
</frame>
myFrame.onMouseUp = 'handleOnMouseUp();';
 
可用性
适用于 3.0 版或更高版本。
 
onMouseWheel当在框体上移动鼠标滚轮时调用
说明
onMouseWheel 属性指定了当用户将鼠标滚轮停留在对象上时，将要执行的 JavaScript 程序代码。
delta 值可从 system.event.scrollDelta 中取得。
通常无须使用此工具，因为当滚动条连接到框体上之后，会自动处理鼠标滚轮。
 
JavaScript
myObjectName.onMouseWheel
 
范例
<frame>
<onMouseWheel>
handleOnMouseWheel(system.event.scrollDelta);
</onMouseWheel>
</frame>
myFrame.onMouseWheel = 'handleOnMouseWheel(
system.event.scrollDelta);';
可用性
适用于 3.0 版或更高版本。
 
onMultiClick 多次按下鼠标按键时调用
说明
无论何时调用onMultiClick 句柄，都可以检查 system.event.clickCount 以查看其数值。
也可以在 onMouseUp 句柄中检查此 system.event.clickCount，以替代 onMultiClick。但是，
使用 onMultiClick 的好处在于它不会像 onMouseUp 一样干扰窗口的拖曳。

范例
<onMultiClick>
if ( system.event.clickCount == 2 )
alert( "Double Click!" );
</onMultiClick>
可用性
适用于 3.0 版或更高版本。
 
 
opacity 对象的透明度
说明
opacity 属性可以让你指定从 0 到 255 之间的数值，它可以控制对象转译时所使用的 alpha 数
值。透明度为 0 表示完全透明 (不可见)，而且可以防止对象响应鼠标事件。
 
范例
<frame>
<opacity>128</opacity>
</frame>
myFrame.opacity = 33;
 
可用性
适用于 3.0 版或更高版本。
scrollX 水平滚动位移
说明
scrollX 属性可让用户指定水平滚动位移。例如，将此属性设定为 -10 会将框体内容向左滚动 10
个像素。通常你无须直接修改此属性。只需将滚动条连接到框体上即可在需要滚动内容时更新此属性。
 
范例
<frame>
<scrollX>-10</scrollX>
</frame>
myFrame.scrollX = -20;
 
可用性
适用于 3.0 版或更高版本。
 
 

scrollY 垂直滚动位移
说明
scrollX 属性可让你指定垂直滚动位移。例如，将此属性设定为 -10 会将框体内容向上滚动 10 个
像素。通常无须直接修改此属性，只需将滚动条连接到框体上即可在需要滚动内容时更新此属性。
 
范例
<frame>
<scrollY>-10</scrollY>
</frame>
myFrame.scrollY = -20;
 
可用性
适用于 3.0 版或更高版本。
 
vAlign 控制对象的垂直对齐
说明
对象的 vAlign 属性可以定义它的位置与它的 vOffset 之间的垂直关系。例如，将会显示 bottom
对齐的图片，以使其底部边缘显示在 vOffset 上。如果未指定此标签，默认值则为 "top"。
有效值包括："top"、"bottom" 或 "center"。
 
JavaScript
myObjectName.vAlign
 
范例
<frame>
<vAlign>bottom</vAlign>
</frame>
myFrame.vAlign = "bottom";
 
可用性
适用于 3.0 版或更高版本。
 
 
visible 控制对象可见与否
说明
设定图片的可见属性，可分别将其设定为 true 或 false 来显示或隐藏图片。这可以让你隐藏对
象，而不会影响它们的透明度，或无须存放目前的透明度以便稍后还原之用。如未指定，任何对象的
默认可见与否都是 true。
JavaScript
myObjectName.visible

范例
<frame>
<visible>false</visible>
</frame>
myFrame.visible = true;
 
可用性
适用于 3.0 版或更高版本。
 
vLineSize 滚动时使用的数据行的大小
说明
vLineSize 属性指定了调用 lineUp() 或 lineDown() 函数时框体应滚动的距离 (像素)。当框体
对鼠标滚轮做出响应时 (如果已连接滚动条)，则也将它列为重要因素。默认的行大小为 10 个像素。
JavaScript
myObjectName.vLineSize
 
范例
<frame>
<vLineSize>5</vLineSize>
</frame>
myFrame.vLineSize = 5;
 
可用性
适用于 3.0 版或更高版本。
 
vOffset 垂直位移
说明
vOffset 属性以0,0（父视图的左上角）作为基点为对象定义垂直 (从上到下) 的位移。指定的
数值越大，对象就画得越往下。
 
JavaScript
object.vOffset
 
范例
<frame>
<vOffset>20</vOffset>
</frame>
可用性
适用于 3.0 版或更高版本。

vScrollBar 垂直滚动条
说明
框体的 vScrollBar 属性定义了哪个滚动条对象应控制此框体的垂直滚动。当以 XML 表示时，可
以指定要绑定至其 vScrollBar 框体的 <scrollbar> 对象的名称。如果滚动条对象不存在，Widget 调
试窗口中将会显示出错误信息。
附加滚动条将会自动设定以便在框体与滚动条之间进行通讯。
 
JavaScript
myObjectName.vScrollBar
 
范例
<frame>
<vScrollBar>my_scrollbar</vScrollBar>
</frame>
<scrollbar name="my_scrollbar" ... />
// 在 Javascript 中：
myFrame.vScrollBar = my_scrollbar;
 
可用性
适用于 3.0 版或更高版本。
 
 
width 对象的宽度
说明
width 属性可以控制对象的水平大小。如果未指定 (或设定为 -1)，框体将使用其子视图的垂直
范围来决定其大小。
 
JavaScript
myObjectName.width
 
范例
<frame>
<width>300</width>
</frame>
myFrame.width = 200;
 
可用性
适用于 3.0 版或更高版本。
 
 

window 此对象所属的窗口。
说明
可以在 XML 中指定对象名称或在 JavaScript 中通过变量来指定对象所属的窗口。如果没有指定
窗口，对象就会自动附加到在 Widget 的 XML 说明中找到的第一个窗口。
 
JavaScript
myObjectName.window
 
范例
<window name="fred" width="100" height="100"/>
<frame>
<window>fred</window>
</frame>
// 或在程序代码中
var myWind = new Window();
myFrame.window = myWind;
// 也可以在结构式中指定它
var myFrame = new Frame( myWind );
可用性
适用于 3.0 版或更高版本。
zOrder 对象的显示顺序
说明
zOrder 属性可以定义对象的显示顺序。zOrder 较高的对象会画在 zOrder 较低的对象之上。一
般情况下，zOrder 是由在 XML 文件中定义对象的顺序来决定的，较早显示的对象在较晚显示的对象
的下方，它也可以在 runtime 中使用 JavaScript 来操纵。
 
JavaScript
myObjectName.zOrder
 
范例
<frame>
<zOrder>10</zOrder>
</frame>
myFrame.zOrder = customZOrder++;
 
可用性
适用于 3.0 版或更高版本。
 

<hotkey> 定义热键及相关默认属性的标签
属性 (Attributes)
key
modifier
name
onKeyDown
onKeyUp
 
说明
XML 文件中的 hotkey 标签可以为 Widget 中的热键定义初始按键及辅助按键。热键是系统级的
按键触发器，它允许通过键盘来存取 Widget。举例来说，可以将搜寻 Widget 的功能设计为
Control+Shift+F2 组合键。
热键对象也可以通过 JavaScript 引擎动态建立及废除。如果允许用户自订 Widget 热键，这将
会很有用。
请注意，有些组合键是系统保留的 (例如，Windows 上的 Control+Tab 或 Mac OS X 上的
Command+Tab)。在 Mac OS X 上，如有多个 Widget 或应用程序使用相同的热键，则当用户按下那些
按键时就会收到通知。
 
JavaScript
newObjectName = new HotKey()
delete newObjectName
 
范例
<hotkey name="hkey1">
<key>F4</key>
 <modifier>control+shift</modifier>
 <onKeyDown>focusWidget();</onKeyDown>
</hotkey>
 
key 功能键的名称
说明
在 Mac OS X 上，可以为以下任何按键定义热键：
Delete、End、Escape、ForwardDelete、F1、F2、F3、F4、F5、F6、F7、F8、F9、F10、F11、F12、
F13、F14、F15、F16、Help、Home、PageDown、PageUp、Space、Tab
 
在 Windows 上可以使用以下的按键：
UpArrow、DownArrow、LeftArrow、RightArrow、F1、F2、F3、F4、F5、F6、F7、F8、F9、F10、
F11、F12、F13、F14、F15、F16、Insert、ForwardDelete、Home、End、PageUp、PageDown、Help、
Clear、PrintScreen、ScrollLock、Pause、Enter、Return、Backspace、Delete、Space、Tab、Escape
依照默认，至少需要一个辅助按键，在 Mac OS X 上为 Command 而在 Windows 上则为 Control。
也可以为任意字母或标点符号按键定义热键，但是在这种情况下必须指定两个辅助按键 (避免用
户因相似的组合键产生的意外效果而感到混淆)。

 
JavaScript
myObjectName.key
 
范例
<hotkey name="hkey1">
<key>F2</key>
</hotkey>
hkey1.key = "F2";
 
modifier 热键的辅助按键
说明
辅助按键属性可为以下的任意组合：
在 Mac OS X 上：command、control、option、shift
在 Windows 上：control、alt、shift
依照默认，辅助按键随时可以使用，并且在 Mac OS X 上为「命令键」，或在 Windows 上为「控
制键」。
 
JavaScript
myObjectName.key
 
范例
<hotkey name="hkey1">
<key>Home</key>
<modifier>control+shift</modifier>
</hotkey>
hkey1.key = "F2";
 
name 热键的名称
说明
hotkey 标签的 name 属性定义可由 JavaScript 操纵的按键名称。由于名称要用来在程序代码中
应用，它不可以包含任何空格或非 ASCII 字符。一经指定，对象名称将无法改变。
当通过 JavaScript 建立动态对象时，可以使用变量的名称来代表对象的新名称。
 
JavaScript
newObjectName = new HotKey()
 
范例
<hotkey name="hkey1">
<key>F2</key>
</hotkey>
hkey1.key = "F2";

 
 
onKeyDown 按下热键时调用
说明
按下热键时要执行的程序代码可以使用 onKeyDown 属性指定。请注意，在 Mac OS X 上将按键码
附加到 onKeyUp 动作上通常是最好的处理方法，因为这是用户期待的方法；但是，只有在 Windows 上
才能触发 onKeyDown。
JavaScript
newObjectName = new HotKey()
 
范例
<hotkey name="hkey1">
<key>F10</key>
 <modifier>control</modifier>
 <onKeyDown>
print("Hotkey " + system.event.keyString +
" pressed");
</onKeyDown>
</hotkey>
 
onKeyUp 松开热键时调用
说明
放开热键时要执行的程序代码可以使用 onKeyUp 属性指定。
按下 Widget 热键时要执行的操作通常是 focusWidget()。
 
JavaScript
newObjectName = new HotKey()
 
范例
<hotkey name="hkey1">
<key>F10</key>
 <modifier>control</modifier>
<onKeyUp>focusWidget();</onKeyUp>
</hotkey>
Windows 注意事项
此触发器不适用于 Windows。
 

<image> 定义图片及相关默认属性的标签
属性 (Attributes)
alignment
clipRect
colorize
contextMenuItems
fillMode
height
hAlign
hOffset
hRegistrationPoint
hslAdjustment
hslTinting
loadingSrc
missingSrc
name
onContextMenu
onDragDrop
onDragEnter
onDragExit
onImageLoaded
onMouseDown
onMouseEnter
onMouseExit
onMouseMove
onMouseUp
onMultiClick
opacity
remoteAsync
rotation
src
srcHeight
srcWidth
tileOrigin
useFileIcon
visible
vAlign
vOffset
vRegistrationPoint
width
window
zOrder
 
说明

XML 文件中的 image 标签可以为 Widget 中的静态图片对象定义初始位置及鼠标事件代码。
图片对象也可以通过 JavaScript 引擎动态建立及清除。如果正在建立含有不确定项目数的
Widget，它将会很有用。
当建立了多个具有相同名称的动态对象时，只有最后建立的一个对象将能通过 JavaScript 接收
属性改变事件。因此应该确定调用的是每个动态对象的唯一名称(使用 JavaScript 数组通常是好方
法)。
更详细的信息请参见 Stock Ticker Widget 中的使用方式。
可以使用 JavaScript delete 指令来删除它。
 
JavaScript
newObjectName = new Image() delete newObjectName
 
范例
<image src="Images/Sun.png" name="sun1">
<hOffset>250</hOffset>
<vOffset>250</vOffset>
<height>20</height>
<width>30</width>
<alignment>center</alignment>
</image>
alignment 图片从原始对齐的方向
说明
定义图片的初始水平对齐。例如，right 对齐的图片将会被显示，以使其右边缘显示在 hOffset 上
(请参见以下内容)。默认对齐方式为 left。
有效数值包括：left、right 或 center。
 
JavaScript
myObjectName.alignment
 
范例
<image src="button.png">
<alignment>right</alignment>
</image>
myButton.alignment = "left";
 
clipRect 控制图片的可见部分。
说明
可以用矩形来设定图片显示的部分。坐标是以 X、Y、宽度、高度的顺序指定的。
JavaScript
myObjectName.clipRect
 

范例
如果你有一个 100x100 的图片，且只想显示从 20, 20 开始到 50, 50 的标签，可以将这个标签
加到 图片中：
<image>
 ...
 <clipRect>20, 20, 30, 30</clipRect>
</image>
也可以随时在 Javascript 中设定或清除它：
myImage.clipRect = "20, 20, 30, 30";
myImage.clipRect = null;
可以将它设定为空白字符串及空值来予以清除。
 
可用性
适用于 2.0 版或更高版本。
 
 
colorize 控制图片的整体色彩
说明
色彩化将图片变成灰阶，并指定色彩，然后将色彩对映到灰阶上。可以使用这个动作来完成深褐
色调效果，以及产生其它各种有趣且十分有用的效果。
 
JavaScript
myObjectName.colorize
 
范例
<image>
...
colorize>#993333</colorize>
</image>
 
若要清除色彩化，只需在 程序代码中将它设定为空值或空白字符串即可：
myImage.colorize = "";
Windows note: 某些 8 位的图片格式 (GIF) 可能无法达到很好的色彩化效果。
 
可用性
适用于 2.0 版或更高版本。在 3.0 版或更高版本中，可以使用 "r:0; g:0; b:0" 格式。
 
contextMenuItems 指定菜单条目的数组。
说明
可以将项目加到用户在框体上点击鼠标右键时所弹出的菜单中。可以在 onContextMenu 标签上执
行某些 JavaScript 来动态地建立 菜单项目 (关于更进一步信息，请参见 onContextMenu)。

可以包含 menuItem 对象数组来指定 项目。（关于更进一步信息，请参见有关 menuItem 的小节
说明）
 
JavaScript
myObjectName.contextMenuItems
 
范例
<image>
...
<contextMenuItems>
<menuItem title="Test" onSelect="beep();"/>
<menuItem title="Another Test">
<onSelect>alert( 'hello' );</onSelect>
</menuItem>
</contextMenuItems>
</image>
请参见 onContextMenu 小节中有关在 JavaScript 中建立菜单的范例。
 
可用性
适用于 2.0 版或更高版本。
 
fillMode 指定图片填入的方式
说明
通常，如果指定了图片的宽度与高度，图片将会延伸填满此区域，此标签可让图片覆盖这个区域，
并可通过指定「并排显示」或「延伸」来取代延伸或并排显示。如果使用并排显示，也可能需要使用
tileOrigin 标签 (稍后说明)。
如果未指定此标签，默认填入模式为「延伸」。
 
JavaScript
myObjectName.fillMode
 
范例
<image>
...
 <fillMode>tile</fillMode>
<tileOrigin>bottomLeft</tileOrigin>
</image>
也可以在 JavaScript 中设定图片的这些属性。
 
可用性
适用于 2.0 版或更高版本。
 

height 图片的高度
说明
height 属性控制图片的垂直尺寸。如果未指定任何高度，将会以图片的「自然」高度来显示图片
(也就是说，无论来源图片的高度是多少)。如果高度大于自然高度，fillMode 属性将会控制发生的情
形 (默认值为拉长图片)。
 
JavaScript
myObjectName.height
 
范例
<image src="button.png">
<height>30</height>
</image>
myButton.height = 30;
 
hAlign 控制图片的水平对齐。
说明
这是对齐标签的同义字。请参见该标签的说明来了解详细信息。
 
可用性
适用于 2.0 版或更高版本。
 
hOffset 图片的水平位移
说明
图片标签的 hOffset 属性以0,0（父视图的左上角）作为基点为图片定义水平 (从左到右) 的
位移。数值越大，图片就会画得越往右。
 
JavaScript
myObjectName.hOffset
 
范例
<image src="button.png">
<hOffset>30</hOffset>
</image>
 
hRegistrationPoint 定义登录点的水平位移
说明

 
hRegistrationPoint 属性定义放置或旋转图片的水平位移。例如，如果有一个 8x8 的图片，将
hRegistrationPoint 设定为4，图片会在hOffset 基础上居中显示。
 
JavaScript
myObjectName.hRegistrationPoint
 
范例
<image src="hourHand.png">
<hRegistrationPoint>4</hRegistrationPoint>
</image>
注意
此属性无法与 hAlign/vAlign 搭配使用。如果尝试将某些项目对齐边缘或将其置中，请使用别的
标签，保留此标签以用于旋转。
 
hslAdjustment 按 HSL (色调 - 饱和度 - 亮度) 来调整图片。
说明
“HSL 调整”可以改变色调，色彩饱和度与亮度。色调可在 -180 到 +180 的范围中调整，饱和
度可在 -100 到 +100 的范围中调整。亮度可在 -100 到 +100 的范围中调整。请记住，增加亮度可
能也会影响饱和度。
 
JavaScript
myObjectName.hslAdjustment
 
范例
<image>
 ...
 <hslAdjustment>-20, 5, 0</hslAdjustment>
</image>
若要清除任何调整，只需在程序代码中将它设定为空值或空白字符串即可：
myImage.hslAdjustment = "";
 
Windows 注意事项：
某些 8 位的图片格式 (GIF) 使用此功能时可能无法达到很好的效果。
 
可用性
适用于 2.0 版或更高版本。
 
 
 

hslTinting 使用 HSL 给图片着色。
说明
「HSL 着色」 可以在调整亮度的同时设定色调与色彩饱和度。色调可以设定为 0 到 360 的范围
之内，饱和度可以设定为 0 到 +100 的范围之内。亮度可以设定为 -100 到 +100 的范围之内。增加
亮度可能也会影响饱和度。
 
JavaScript
myObjectName.hslTinting
 
范例
<image>
...
<hslTinting>-20, 5, 0</hslTinting>
</image>
若要清除着色，只需在 程序代码中将它设定为空值或空白字符串即可：
myImage.hslTinting = "";
 
Windows 注意事项：
某些 8 位的图片格式 (GIF) 使用此功能时可能无法达到很好的效果。
 
可用性
适用于 2.0 版或更高版本。
 
loadingSrc 图片异步加载时显示图片的路径
说明
如果异步加载远程图片 (通过将 remoteAsync 设定为 true)，就可以在它的位置显示替代图片，
同时通过设定此属性来从服务器中获取图片。图片最终加载后，它会自动取代 loadingSrc。如果要在
发生这种情况时收到通知，请通过 onImageLoaded 属性来指定要发生的动作。
 
JavaScript
myImage.loadingSrc = "images/loading.png";
 
范例
<image src="http://www.imadethisup.com/remote.jpg">
<loadingSrc>images/loading.png</loadingSrc>
<remoteAsync>true</remoteAsync>
</image>
 
可用性
适用于 3.0 版或更高版本。
 

missingSrc 无法加载 src 时显示图片的路径
说明
当图片的 src 属性无法加载时，此属性可用来自订显示的图片。Widget Engine 拥有适用于这种
情况的默认「遗失」图片，但并可能非适用于所有情况。通常，当加载不存在或无法存取的远程来源
时，便可以使用它。
 
JavaScript
myImage.missingSrc = "images/missing.png";
 
范例
<image src="http://www.imadethisup.com/notthere.jpg">
<missingSrc>images/missing.png</missingSrc>
</image>
可用性
适用于 3.0 版或更高版本。
 
name 图片的名称
说明
image 标签的 name 属性可以定义由 JavaScript 应用时的图片名称。由于名称要用来在程序代
码中应用，因此它不可以包含任何空格或非 ASCII 字符。
一经指定，对象名称将无法改变。
当通过 JavaScript 建立动态对象时，可以使用变量的名称来代表对象的新名称。
 
JavaScript
newObjectName = new Image()
 
范例
<image src="button.png">
<name>myButton</name>
</image>
myButton.hOffset = 22;
 
onContextMenu
说明
要为 Widget 指定被加到标准菜单中的菜单项目，最简单的方法就是在 XML 中使用
contextMenuItems 标签。但是，对于那些需要动态建立其项目的 Widget 来说，onContextMenu 句柄
是你最好的工具。当即将要显示菜单时，在某些视图响应之前，它会按照视图顺序从前到后在鼠标底
下针对所有元素调用。处理此情况时，你只须建立菜单项目，并将 contextMenuItems 属性设定为项
目的数组即可。

 
JavaScript
myImage.onContextMenu
 
范例
<onContextMenu>
var items = new Array();
items[0] = new MenuItem();
items[0].title = "This is the title";
items[0].enabled = false;
items[0].checked = true;
items[0].onSelect = "alert( 'you chose it!' );";
items[1] = new MenuItem();
items[1].title = "This is the second title";
items[1].onSelect = "beep();";
myImage.contextMenuItems = items;
</onContextMenu>
可用性
适用于 2.0 版或更高版本。
 
onDragDrop 将某些项目放到对象上时，便调用此代码
说明
将文件、URL 或字符串从其它应用程序 (如 Finder) 中拖曳出来，并放到对象上时，onDragDrop
触发器便会触发。
在 onDragDrop 中，动作对象可以存取 system.event.data 来查看拖放的内容。这是字符串数组，
其第一个元素指定了拖放对象的类型：filenames、urls 或 string。数组的其它元素是被拖放的项目。
 
JavaScript
myObjectName.onDragDrop
 
范例
<image src="button.png">
<name>myButton</name>
<onDragDrop>
 if (system.event.data[0] == "filenames")
 {
processDroppedFiles(system.event.data);
}
</onDragDrop>
</image>
 
<image src="button.png" name="myButton">
<onDragDrop>dragCode.js</onDragDrop>

</image>
myButton.onDragDrop = "handleDragDrop();";
 
onDragEnter 将项目拖曳到对象中时被调用
说明
image 标签的 onDragEnter 属性是当用户已将项目从其它应用程序中拖曳到对象中时将被调用的
JavaScript 函数。在拖放项目之前会发生此种情况 (实际上它可能不会被拖放，因为用户的想法会改
变)。
这可以用来触发对象的外观发生变化，以指示用户如果拖放对象，将会接受还是拒绝被拖曳的对
象。有关拖曳项目的信息，可查阅 system.event.data (如需详细信息，请参见 onDragDrop)。
 
JavaScript
myObjectName.onDragEnter
 
范例
<image src="well.png">
<name>well</name>
<onDragEnter>
highlightDropTarget(well);
</onDragEnter>
</image>
well.onDragEnter = "highlightDropTarget(well);";
 
onDragExit 将项目拖曳到对象外时被调用
说明
image 标签的 onDragExit 属性是当用户已将项目从其它应用程序中拖曳到对象中然后再拖出去
时将被调用的 JavaScript 函数。
对于取消已在 onDragEnter 中执行的项目来说，这是很有用的。
 
JavaScript
myObjectName.onDragExit
 
范例
<image src="well.png">
<name>well</name>
<onDragExit>
unhighlightDropTarget(well);
</onDragExit>
</image>
well.onDragExit = "unhighlightDropTarget(well);";
 

onImageLoaded 完成异步加载图片时调用
说明
如果图片的 src 属性指向远程图片，且将 remoteAsync 属性设定为 true，则会异步获取图片。
如果需要了解图片何时会最终加载，可以使用此动作来在图片完成加载时取得通知。例如，可以将图
片大小重新调整为图片目前的原始大小，或者按比例调整它的大小。
 
JavaScript
myObjectName.onImageLoaded
 
范例
<image src="http://www.some.remote.image.com/image.png">
<onImageLoaded>
print( "image done loading" );
</onImageLoaded>
</image>
myImage.onImageLoaded = "print( 'image loaded' );";
可用性
适用于 3.0 版或更高版本。
 
 
onMouseDown 在对象上按下鼠标按键时调用
说明
image 标签的 onMouseDown 属性是当用户在对象中按下鼠标按键时将被调用的 JavaScript 函
数。对于根据按下的状态触发对象的外观发生变化来说，这是很有用的。
 
JavaScript
myObjectName.onMouseDown
 
范例
<image src="button.png">
<name>myButton</name>
<onMouseDown>
myButton.src = "buttonDown.png";
</onMouseDown>
</image>
<image src="button.png" name="myButton">
<onMouseDown>buttonCode.js</onMouseDown>
</image>
myButton.onMouseDown = "doButtonHighlight(myButton);";
 
 

onMouseEnter 当鼠标移动到对象中时被调用
说明
image 标签的 onMouseEnter 属性是当用户在对象中移动光标时将被调用的 JavaScript 函数。
对于根据在其上方滚动的状态来触发对象的外观发生变化，或对于除非你在 Widget 上移动，否
则就会显示的隐藏对象来说，它是很有用的。
 
JavaScript
myObjectName.onMouseEnter
 
范例
<image src="button.png">
<name>myButton</name>
<onMouseEnter>
myButton.src = "buttonOver.png";
</onMouseEnter>
</image>
myButton.onMouseEnter = "handleMouseEnter(myButton);";
 
onMouseExit当鼠标移动到对象外时被调用
说明
image 标签的 onMouseExit 属性是当用户将光标从对象中移动到对象外时将被调用的
JavaScript 函数。
对于根据在其上方滚动的状态来触发对象的外观发生变化，或对于除非你在 Widget 上移动，否
则就会重新隐藏已经隐藏的对象来说，它是很有用的。
 
JavaScript
myObjectName.onMouseExit
 
范例
<image src="button.png">
<name>myButton</name>
<onMouseExit>
myButton.src = "button.png";
</onMouseExit>
</image>
myButton.onMouseExit = "handleMouseExit(myButton);";
 
onMouseMove 当鼠标在对象中移动时被调用
说明
image 标签的 onMouseMove 属性是当用户将鼠标光标拖曳到对象的范围内时将被调用的

JavaScript 函数。目前的鼠标位置可以在 system.event 对象中使用。
这可以用于在 Widget 周围移动对象。iTunes Remote Widget 中的音量滚动条也可以使用此动作
来内建。
 
JavaScript
myObjectName.onMouseMove
 
范例
<image src="button.png">
<name>myButton</name>
<onMouseMove>
 print(system.event.x + ", " + system.event.y);
</onMouseMove>
</image>
myButton.onMouseMove = "handleMouseMove(myButton);";
 
 
 
onMouseUp 在对象中放开已经按下鼠标按键时被调用
说明
image 标签的 onMouseUp 属性是当用户在对象中按下鼠标按键之后再放开它时将被调用的
JavaScript 函数。
对于根据按下的状态触发对象的外观发生变化来说，这是很有用的。
请注意，即使放开鼠标按键时鼠标不在对象内，onMouseUp 也会触发。要建立拥有正确鼠标事件
的按钮，必须使用所有四个鼠标事件句柄，以传送鼠标的状态及其交集状态 (关于此项目的范例，请
参见随附的 Calendar Widget)。
 
JavaScript
myObjectName.onMouseUp
 
范例
<image src="button.png">
<name>myButton</name>
<onMouseUp>
myButton.src = "button.png";
</onMouseUp>
</image>
myButton.onMouseUp = 'handleOnMouseUp(myButton);';
 
onMultiClick 多次按下鼠标按键时调用
说明
此句柄可以在图片、文字、文字标签与窗口对象上设定，无论何时调用 onMultiClick，都可以

检查 system.event.clickCount 以查看其数值。
 
也可以在 onMouseUp 句柄中检查 system.event.clickCount，替代onMultiClick。但是，使用
onMultiClick 的好处在于它不会像 onMouseUp 一样干扰窗口拖曳。如果 图片需要响应鼠标多击，就
可以使用 onMultiClick，而且 Widget 能够像平常一样拖曳。
<onMultiClick>
if ( system.event.clickCount == 2 )
alert( "Double Click!" );
</onMultiClick>
可用性
适用于 2.0 版或更高版本。
opacity 图片的透明度
说明
opacity 属性可以让你指定 0 到 255 之间的某个数值。透明度为 0 表示完全透明 (不可见)，
而且有防止对象响应鼠标事件的效果。
 
范例
<image src="button.png">
<name>myButton</name>
<opacity>128</opacity>
</image>
myButton.opacity = 33;
 
remoteAsync 指定是否异步获取远程图片
说明
当设定为 true 时，remoteAsync 会告知图片对象在后台中加载图片来源，以让 Widget 能够同
时做其它事情。如果要指定在获取图片时显示图片，可以设定 loadingSrc 属性。如果要在最终加载
图片时得到通知，请使用一些适当的 Javascript 来设定 onImageLoaded 属性。
 
范例
<image src="http://www.a.remote.server.com/image.png">
<loadingSrc>images/loading.png</loadingSrc>
<remoteAsync>true</remoteAsync>
</image>
myImage.remoteAsync = true;
 
可用性
适用于 3.0 版或更高版本。

rotation 图片顺时针旋转的度数
说明
图片标签的 rotation 属性是由 image 旋转的度数或度数的小数来定义的。
旋转可以用于各种目的，但是大多数明显的范例都是用来精确地代表模拟时钟的指针。
 
JavaScript
myObjectName.rotation
 
范例
<image src="hourHand.png">
<rotation>
180
</rotation>
</image>
 
src 图片的路径
说明
image 标签的 src 属性可以定义图片的来源。它在硬盘机上使用了它所应用的与 Widget 的 XML
文件相关的文件路径。
在 2.0 版或更高版本中，可以将 URL 指定为图片的来源。
 
JavaScript
myObjectName.src
 
范例
<image src="Resources/Buttons/button.png">
 
srcHeight 图片的原始高度
说明
srcHeight 属性提供了图片的原始高度，这与在重新调整大小之前从磁盘中读取的高度相同。此
属性是只读的，设定它不会产生任何影响。
 
JavaScript
myObjectName.srcHeight
 
范例
origHeight = myButton.srcHeight;

srcWidth 图片的原始宽度
说明
srcWidth 属性提供了图片的原始宽度，这与在重新调整大小之前从磁盘中读取的宽度相同。此属
性是只读的，设定它不会产生任何影响。
 
JavaScript
myObjectName.srcWidth
 
范例
origWidth = myButton.srcWidth;
 
tileOrigin 控制图片并排显示的方式
说明
此标签是与 fillMode 标签一起使用的，如上所述。如果将 fillMode 设定为「并排显示」，图片
就会以其宽度及高度并排显示 (假设它们比图片的自然大小大)。此标签可以控制从图片的哪一角开始
并排显示。有效数值包括 "topLeft"、"topRight"、"bottomLeft" 及 "bottomRight"。如果未指定此
标签，默认值则为 "topLeft"。
 
JavaScript
myObjectName.tileOrigin
 
范例
<image>
...
 <fillMode>tile</fillMode>
<tileOrigin>bottomLeft</tileOrigin>
</image>
也可以在 Javascript 中完美设定它们。
 
可用性
适用于 2.0 版或更高版本。
tooltip 图片对象的工具提示
说明
tooltip 属性可以定义当鼠标光标停留在 image 对象上时显示在popup式工具提示窗口中的文
字。
 
JavaScript
object.tooltip
 
范例

<image src="Example.png">
<tooltip>Example tooltip</tooltip>
</image>
tracking 图片的光标跟踪样式
说明
tracking 属性可以指定图片的透明度是否应该用来判断图片的可点击部分，而不是周框。依照默
认，图片的透明部分是不可以点击的，但是可以将 tracking 属性改变为可以使整个图片响应点击鼠
标键动作的 rectangle 来改变它。
 
JavaScript
myObjectName.tracking
 
范例
<tracking>rectangle</tracking>
参见：defaultTracking
 
useFileIcon 获取文件的图示
说明
image 标签的 useFileIcon 属性可以指定将会使用在 src 中指定的文件的图示来初始化此图
片。请注意，在这种情况下，src 可以应用任何文件，而不只是包含图片数据的文件。
 
JavaScript
myObjectName.src
 
范例
<image useFileIcon="true">
<src>/Applications/iChat.app</src>
</image>
 
vAlign 控制图片的垂直对齐
说明
图片的 vAlign 属性可以定义它的位置与它的 vOffset 之间的垂直关系。例如，bottom 对齐的
图片将会被显示，以使其底部边缘显示在 vOffset (请参见以下说明)。如果未指定此标签，默认值则
为 top。
有效数值包括：top、bottom 或 center。
 
JavaScript
myObjectName.vAlign

范例
<image src="button.png">
<vAlign>bottom</vAlign>
</image>
myButton.vAlign = "bottom";
 
可用性
适用于 2.0 版或更高版本。
visible 控制图片可见与否
说明
可以设定图片的可见属性，可分别将其设定为 true 或 false 来显示或隐藏图片。这可以让你隐
藏对象，而不会影响它们的透明度，或无须存放目前的透明度以便稍后还原之用。如未指定，任何对
象的默认可见与否都是 true。
 
JavaScript
myObjectName.visible
 
范例
<image src="button.png">
<visible>false</visible>
</image>
myButton.visible = true;
 
可用性
适用于 3.0 版或更高版本。
 
vOffset图片的垂直位移
说明
image 标签的 vOffset 属性以0,0（父视图的左上角）作为基点为图片定义垂直 (从上到下) 的
位移。指定的数值越大，图片就画得越往下。
vOffset 可以指定文字的基准线位于何处。如果你没有设定它，你可能无法看到文字，因为基准
线将为零。
 
JavaScript
object.vOffset
 
范例
<image src="button.png">
<vOffset>20</vOffset>
</image>

vRegistrationPoint 定义登录点的垂直位移
说明
image 标签的 vRegistrationPoint 属性可以定义用来放置图片的垂直位移。例如，如果有一个
8x8 的图片，且将 vRegistrationPoint 设定为 4，图片将会在你提供的 vOffset 上置中显示。
 
JavaScript
myObjectName.vRegistrationPoint
 
范例
<image src="hourHand.png">
<vRegistrationPoint>36</vRegistrationPoint>
</image>
 
注意：
此属性无法与 hAlign/vAlign 正常搭配使用。如果你尝试将某些项目对齐边缘或将其置中，请使
用那些标签，并保留此标签以用于旋转。
width图片的宽度
说明
width 属性可以控制图片的水平尺寸。如果未指定任何宽度，将会以图片的「自然」宽度来显示
图片 (也就是说，无论来源图片的宽度是多少)。如果宽度大于自然宽度，fillMode 属性将会控制发
生的情形 (默认值为拉长图片)。
 
JavaScript
myObjectName.width
 
范例
<image src="button.png">
<width>30</width>
</image>
myButton.width = 20;
 
window 图片所属的窗口。
说明
可以在 XML 中指定图片名称或在 JavaScript 中指定其变量来指定图片所属的窗口。如果你没有
指定窗口，图片就会自动附加到在 Widget 的 XML 说明中所找到的第一个窗口。
 
JavaScript
myObjectName.window
 
范例

<window name="fred" width="100" height="100"/>
<image src="button.png">
<window>fred</window>
</image>
// 或在程序代码中
var myWind = new Window();
myImage.window = myWind;
// 也可以在图片的结构式中指定它
var myImage = new Image( myWind );
 
可用性
适用于 2.0 版或更高版本。
 
zOrder 图片的显示顺序
说明
image 标签的 zOrder 属性可以定义图片的显示顺序。zOrder 较高的对象会画在 zOrder 较低的
对象之上。一般情况下，zOrder 是由在 XML 文件中定义对象的顺序来决定的，较早显示的对象在较
晚显示的对象的下方，不过它也可以在 runtime 中使用 JavaScript 来操纵。
 
JavaScript
myObjectName.zOrder
 
范例
<image src="button.png">
<zOrder>10</zOrder>
</image>
myButton.zOrder = customZOrder++;
 
 
<menuItem>定义菜单项目的标签
属性 (Attributes)
checked
enabled
onSelect
title
 
说明
菜单项目可以由菜单数组及句柄使用，为标准 Widget 菜单提供其它项目。
 
可用性
适用于 2.0 版或更高版本。

checked 指定项目已经经过审核
说明
此属性只能指定当在菜单中显示，项目旁边应该有一个审核标记。如果未指定此属性，默认值将
为 false。
 
范例
<menuItem name="myItem"
title="Widgetz R0x0r!!!11" checked="true"/>
// 或在 JavaScript 中
myItem.checked = true;
 
可用性
适用于 2.0 版或更高版本。
 
enabled 指定项目为可用
说明
此属性只能指定项目应在菜单中启用。如果设定为 false，项目会显示为灰色而且用户将无法选
择它。如果未指定此属性，默认值将为 true。
 
范例
<menuItem title="Recent Locations" enabled="false"/>
// 或在 JavaScript 中
myItem.enabled = false;
可用性
适用于 2.0 版或更高版本。
onSelect 选择项目时将执行的 JavaScript 代码
说明
此属性可以提供要在从菜单中选择项目时执行的动作。
 
范例
<menuItem title="Recent Locations" enabled="false"
onSelect="beep();"/>
// 或在 JavaScript 中
myItem.onSelect = "beep();";
 
可用性
适用于 2.0 版或更高版本。
 

title 指定菜单项目的标题
说明
此属性可以提供为菜单项目显示的文字。
 
范例
<menuItem title="I am the title"/>
// 或在 JavaScript 中
myItem.title = "Choose me!";
 
可用性
适用于 2.0 版或更高版本。
 
 
 
<preference> 定义偏好设置以及相关属性的标签
属性 (Attributes)
defaultValue
description
directory
extension
group
hidden
kind
maxLength
minLength
name
notSaved
option
optionValue
secure
style
ticks
tickLabel
title
type
value
 
说明
偏好标签可以定义将要由 Widget 在打开/关闭工作阶段之间存放的信息标签以及用户输入的数
据。
有两个自动提供的偏好设置：
 

konfabulatorWindowLevel Widget 窗口显示在用户屏幕上的高度
有效值包括floating、topMost、normal、below 或 desktop
 
konfabulatorWindowOpacity Widget 窗口的透明度
这些偏好设置可以让用户控制 Widget 在他们的桌面上显示的方式。如果要自行提供此功能，你
只需要调用 偏好设置相同的名称 windowLevel 与 windowOpacity 即可。如果要停用此功能，只需在
Widget 中定义两个偏好设置即可，如下所示：
 
<preference name="windowLevel">
<hidden>true</hidden>
</preference>
<preference name="windowOpacity">
<hidden>true</hidden>
</preference>
 
defaultValue 偏好设置的默认数值
说明
偏好设置标签的 defaultValue 属性可以指定依照默认值数值应该为何。这样也可以预先产生 偏
好设置，并保留预留位置，直到用户输入正确数据为止。这就是当在用户自订了偏好设置之前，如果
JavaScript 程序代码存取了偏好设置，它将会看到的数值。
范例
<preference name="colorPref">
<defaultValue>red</defaultValue>
</preference>
colorPref.defaultValue = "red";
 
description 在偏好设置面板中显示的文字
说明
偏好标签的说明属性可以定义当显示在偏好设置面板的用户接口中时，位于偏好设置底下的描述
性文字。
它虽然是选用的，但是我们强烈建议使用，以说明偏好设置以及它对于用户的用途。
范例
<preference name="colorPref">
<description>
Enter the desired color
</description>
</preference>

 
directory默认的工作目录
说明
使用此属性来设定工作目录。
 
范例
<preference>
<type>selector</type>
<style>open</style>
<directory>~/Documents</directory>
</preference>
 
extension 偏好设置的文件种类
说明
使用此属性，可以将显示 open 系统对话框的 偏好设置限制为只返回拥有某些扩展名的文件。
 
范例
<preference>
<type>selector</type>
<style>open</style>
<extension>.jpg</extension>
<extension>.gif</extension>
<extension>.png</extension>
</preference>
 
group 偏好设置所属的群组
说明
对于 2.0 版来说，Widget 的「偏好设置」对话框被分为了多个群组，而且会显示在多窗格对话
框中。此属性会通知 Widget Engine 这个特殊偏好设置所属的偏好设置群组。如果未指定此属性，偏
好设置将会自动划分到「一般」群组中。
 
范例
<preference>
<type>selector</type>
<style>save</style>
<group>my_group</group>
</preference>
上述范例假设的是你已经在 XML 的某个地方定义了名为 my_group 的适当偏好设置群组。关于更
进一步信息，请参见有关 preferenceGroup 的小节。

 
可用性
适用于 2.0 版或更高版本。
hidden 像用户隐藏的偏好设置
说明
如果偏好设置具有 hidden 属性，将不会为一般用户提供编辑或查看偏好设置的功能。你仍然可
以在 JavaScript 中操纵此偏好设置，但它将不会显示在「Widget 偏好设置」对话框中。如果 Widget
只有隐藏的偏好设置，那么在菜单中将不会为用户提供「Widget 偏好设置」选项。隐藏的偏好设置通
常都是用来内建用户使用 Widget 上的控件所做的设定，而非通过打开「Widget 偏好设置」对话框所
做的设定。
 
范例
<preference name="colorPref">
<hidden>true</hidden>
<type>text</type>
<defaultValue>red</defaultValue>
</preference>
 
kind 偏好设置的项目类型
说明
可以使用此属性将显示 open 系统对话框的 偏好设置限制为 files、folders 或 both。
 
范例
<preference>
<type>selector</type>
<style>open</style>
<kind>folders</kind>
</preference>
 
maxLength slider 偏好设置的最大数值
说明
目前只能用于滚动条偏好设置，这是滚动条可以代表的最大数值。
 
范例
<preference>
<maxLength>200</maxLength>
</preference>

minLength slider 偏好设置的最小数值
说明
目前只能用于滚动条偏好设置，这是滚动条可以代表的最小数值。
 
范例
<preference>
<minLength>1</minLength>
</preference>
name 偏好设置的名称
说明
由于名称要在程序代码中应用，因此它不应包含任何空格或非 ASCII 字符。
 
范例
<preference>
<name>colorPref</name>
</preference>
 
notSaved 防止偏好设置自动存放
说明
notSaved 属性可以使偏好设置无法自动存放在 Widget 的用户偏好设置文件中。如果要在偏好设
置面板中显示控件，但却要处理在程序代码中返回的数值，此属性就会非常有用。从某种程度上讲，
这个属性与 hidden 是相反的。
 
范例
<preference>
<notSaved>true</notSaved>
</preference>
 
Option 偏好设置的选项
说明
类型 popup 的偏好设置会在「Widget 偏好设置」对话框中显示为popup菜单。某些 option 属
性可以为popup菜单提供一组选项。
为选项指定字符串 (- 可以使分隔符显示在popup菜单中的该点上 (用户无法选择它)。
 
范例
<preference name="colorPref">

<type>popup</type>
<option>Red</option>
<option>White</option>
<option>(-</option>
<option>Blue</option>
</preference>
 
optionValue 选项的数值
说明
如果要在选择 option (请参见上述内容) 时返回不同的数值，请为每个 option 指定一个
optionValue。每个 option 都应该有一个 optionValue (请注意如果使用「分隔符」option，如上所
述，将需要为它提供一个相应的虚拟 optionValue，即使永远也不会返回此数值亦如此)。
 
范例
<preference name="colorPref">
<type>popup</type>
<option>Red</option>
<optionValue>#FF0000</optionValue>
<option>White</option>
<optionValue>#FFFFFF</optionValue>
<option>(-</option>
<optionValue>none</optionValue>
<option>Blue</option>
<optionValue>#0000FF</optionValue>
</preference>
 
secure 指定应安全存放属性数值
说明
任何类型的偏好设置都可以是 secure，来以其数据不会被轻易读取的方式将数据存放起来。这对
于存放密码等项目来说是很有用的。此外，text 偏好设置还可以显示「密码」样式用户接口 (会显示
圆点，而不会显示键入的字符)。
如果读取之前的 secure 偏好设置的程序代码变为不安全，偏好设置的数值将会重设为
defaultValue。
 
范例
<preference>
<type>text</type>
<secure>yes</secure>
</preference>
 

style 偏好设置的对话框样式
说明
 偏好设置可以显示 open 或 save 系统对话框。前者可以让用户选择现有文件，后者是用户可以
存放或建立新文件的地方。
 
范例
<preference>
<type>selector</type>
<style>open</style>
</preference>
 
ticks 显示在 slider 偏好设置上勾选标记的数目
说明
要使滚动条显示勾选标记，请使用 ticks 属性。使用此属性的反效果是滚动条也只能返回与勾号
相应的数值。
对于滚动条来说，minLength 与 maxLength 属性可以定义能够设定的最小与最大数值。第一个勾
号将与 minLength 相应，最后一个勾号则与 maxLength 相应。
 
范例
<preference>
<type>slider</type>
<ticks>10</ticks>
<minLength>0</minLength>
<maxLength>100</maxLength>
</preference>
tickLabel
 
slider 滚动条
说明
要使滚动条在轨道下面显示标签，请指定一或多个 tickLabels。标签会平均分配到滚动条的长度
上。
 
范例
<preference>
<type>slider</type>
<tickLabel>One</tickLabel>
<tickLabel>Volume</tickLabel>
<tickLabel>Eleven</tickLabel>
</preference>
 

title偏好设置的标题
说明
定义显示给用户的标签标题。
 
范例
<preference>
<title>Color:</title>
</preference>
 
 
type 数据与控件的类型
说明
偏好设置标签的类型属性可以定义用户接口对象来显示数据的类型。
类型可以是以下其中一种：
checkbox
用来取得是/否输入的复选框。返回到 Widget 的数值是 0 或 1。
 
 
color
显示色样并让你挑选颜色。返回到 Widget 的数值是标准色号，如 #123456。
 
 
 
font
显示字体名称，并可让你从系统上的可用字体中挑选。「文字」对象的字体属性
可以设定为返回的数值。
 
 
hotkey
显示热键及其辅助按键，并可让选择任何一种组合键。返回的数值可以用来设
定「热键」对象的辅助按键与按键。
 
 
popup
显示选择，并可让你从 Widget 指定的清单中选择。会返回一个字符串 (其中
一个 option，或者若已指定，则为其中一个 optionValue)。
 
 
selector
显示文件名称，并可让选择其它文件名称。返回到 Widget 的数值是完整的文
件路径名称 (具有 / 分隔符的网页样式路径)。
 
 
slider
显示滚动条，并可让你输入数值。会返回数值。
 
 
text
用户可以输入文字的标准文字字段。会返回字符串 (请参见 secure 属性以了
解显示密码样式文字字段的信息)。
 
 
 
范例

<preference>
<type>checkbox</type>
</preference>
 
value 偏好设置目前的值
说明
偏好设置的数值属性中包含指定给偏好设置的目前数值。这可能是由用户刚刚输入的，或者可能
是在启动时从 Widget 的偏好设置文件中读取的。
请注意，即使数值属性中包含数字，它也将一直被视为字符串处理。如果你要将偏好设置数值做
为数字来使用，请在存取它时使用适当的转换例程。例如：
numberOfItems = Number(preferences.numItems.value) + 1;
 
 
<preferenceGroup> 组织偏好设置的群组
属性 (Attributes)
name
icon
order
title
 
说明
偏好设置群组可以让你在显示在「偏好设置」对话框中时组织 偏好设置。在 2.0 版或更高版本
中，此对话框会显示为多窗格对话框。可以先使用 preferenceGroups 来定义 群组，然后再在特殊群
组中设定要的每个偏好设置的群组属性。
 
可用性
2.0 版中会为你介绍偏好设置群组
 
name 群组的名称
说明
此属性可以定义群组名称。这个名称仅仅是一个识别码，而且在所有偏好设置群组中都应该是唯
一的。当定义属于群组的偏好设置项目时，这就是你用来识别它所属群组的名称。你不应将其与标题
属性混淆，标题属性是显示在偏好设置窗口工具列中的用户可以看到的名称。
 
范例
<preferenceGroup name="colors" title="Colors"/>
 
可用性

适用于 2.0 版或更高版本。
 
icon 群组的图标
说明
可以指定显示在对话框中代表 群组的图片。目前此图片最大必须为 32x32。如果你未指定图示，
将会自动为 群组提供一个默认图示。
 
范例
<preferenceGroup icon="Resources/myPrefIcon.png"/>
 
可用性
适用于 2.0 版或更高版本。
 
order 群组的显示顺序
说明
此属性可以用来帮你控制偏好设置群组在对话框中显示的顺序。编号完全由你决定，不过最小的
编号会显示在最左边的位置。
 
范例
<preferenceGroup>
title="First Group"
order="0"
</preferenceGroup>
<preferenceGroup>
title="Second Group"
order="1"
</preferenceGroup>
 
可用性
适用于 2.0 版或更高版本。
 
title 群组的标题
说明
这个属性可以定义应该显示在对话框中偏好设置群组的图标下方的文字。这些标题通常都应该较
短，而且应是一或两个字的长度。
 
范例
<preferenceGroup>
title="General"

order="0"
</preferenceGroup>
<preferenceGroup>
title="Special"
order="1"
</preferenceGroup>
 
可用性
适用于 2.0 版或更高版本。
 
<scrollbar>指定滚动条对象
属性
autoHide
hAlign
height
hOffset
max
min
onValueChanged
opacity
orientation
pageSize
thumbColor
vAlign
value
visible
width
window
zOrder
 
 
autoHide 指定当没有任何需要滚动的内容时，滚动条是否隐藏
说明
此属性可以用来将滚动条设定为当没有要滚动的内容时滚动条将会隐藏的模式。此属性的默认值
为 false。如果未将滚动条设定为自动隐藏，那么当没有要滚动的内容时，它就会变为 50% 透明。
 
范例
<scrollbar>
<autoHide>true</autoHide>
</scrollbar>
 

可用性
m适用于 3.0 版或更高版本。
hAlign 控制对象的水平对齐
说明
对象的 hAlign 属性可以定义与其 hOffset 属性有关的初始水平对齐方式。例如，将会显示 right
对齐的对象，以使其右边缘能够显示在 hOffset 上。默认对齐方视为 "left"。
有效数值包括："left"、"right" 或 "center"。
 
JavaScript
myObjectName.alignment
 
范例
<scrollbar>
<alignment>right</alignment>
</scrollbar>
myScrollbar.alignment = "left";
 
可用性
适用于 3.0 版或更高版本。
 
height 对象的高度
说明
height 属性可以控制对象的垂直尺寸。对于水平滚动条来说，你无须指定高度。滚动条图片的大
小将会决定它。一般而言，你不应该指定高度，而应该询问滚动条其高度是多少，以配置 接口。这样
将会使你未来无法改变滚动条的外观。很明显地，对于垂直滚动条来说，必须将高度设定为 接口所要
求的任何高度。
 
JavaScript
myObjectName.height
 
范例
<scrollbar>
<height>300</height>
</scrollbar>
myScrollbar.height = 300;
 
可用性
适用于 3.0 版或更高版本。
 
 

hOffset 对象的水平位移
说明
对象的 hOffset 属性以0,0（父视图的左上角）作为基点为图片定义水平 (从左到右) 的位移。
指定的数值越大，对象就会越往右显示。
 
JavaScript
myObjectName.hOffset
 
范例
<scrollbar>
<hOffset>30</hOffset>
</scrollbar>
可用性
适用于 3.0 版或更高版本。
 
max 滚动条的最大数值
说明
max 属性可以定义滚动条的最大数值。它可以跟 min 一起定义滚动条所能拥有的数值范围。数值
会固定在 min 与 max 之间。
如果你只是将滚动条连接到框体上，你就再也不需要处理此属性了。在这种情况下，它都会自动
设定。
如果你确实拥有一个独立的滚动条，而且要设定 min，则必须使用 setRange() 函数。你无法在
Javascript 中直接修改此属性。但是，可以在 XML 中为滚动条指定它。
 
JavaScript
myObjectName.max
 
范例
<scrollbar>
<min>0</min>
<max>100</max>
</scrollbar>
 
可用性
适用于 3.0 版或更高版本。
 
min 滚动条的最小数值
说明
min 属性可以定义滚动条的最小数值。它可以跟 max 一起定义滚动条所能拥有的数值范围。数值

会固定在 min 与 max 之间。
如果你只是将滚动条连接到框体上，你就再也不需要处理此属性了。在这种情况下，它都会自动
设定。
如果你确实拥有一个独立的滚动条，而且要设定 max，则必须使用 setRange() 函数。你无法在
Javascript 中直接修改此属性。但是，可以在 XML 中为滚动条指定它。
 
JavaScript
myObjectName.min
 
范例
<scrollbar>
<min>0</min>
<max>100</max>
</scrollbar>
 
可用性
适用于 3.0 版或更高版本。
 
onValueChanged 在滚动条的数值改变时调用
说明
这个属性中包含当滚动条的数值改变时被调用的 Javascript。
如果你只是将滚动条连接到框体上，你就再也不需要为此属性指定任何内容了。框体将会自动对
被拖曳的滚动条做出回应。
 
JavaScript
myObjectName.min
 
范例
<scrollbar name="sb">
<onValueChanged>
print( "Whoa! value is now " + sb.value );
</onValueChanged>
</scrollbar>
 
可用性
适用于 3.0 版或更高版本。
opacity 对象的透明度
说明
opacity 属性可以让你指定从 0 到 255 之间的数值，它可以控制对象转译时所使用的 alpha 数
值。透明度为 0 表示完全透明 (不可见)，而且有防止对象响应鼠标事件的反效果。数值 255 将会以
其自然的透明度转译图片。

范例
<scrollbar>
<opacity>128</opacity>
</scrollbar>
myScrollbar.opacity = 33;
 
可用性
适用于 3.0 版或更高版本。
 
Orientation 滚动条的方向
说明
orientation 属性可以让你指定滚动条的方向。它可能的数值为「垂直」与「水平」。默认值为「垂
直」。
 
范例
<scrollbar>
<orientation>vertical</orientation>
</scrollbar>
myScrollbar.orientation = "horizontal";
 
可用性
适用于 3.0 版或更高版本。
pageSize 页面大小
说明
pageSize 属性可以用来确定按比例显示的滚动条的滚动方块大小。一般情况下，这就是滚动的视
图的高度 (假设是垂直滚动条)。
如果你已经将滚动条连接到「框体」上以用来滚动，你则无须直接处理此属性。它会自动设定及
处理。
 
范例
<scrollbar>
<pageSize>140</pageSize>
</scrollbar>
myScrollbar.pageSize = 100;
 
可用性
适用于 3.0 版或更高版本。
thumbColor滚动条的滚动方块颜色
说明

thumbColor 属性可以用来控制滚动方块的色调。标准滚动条的默认滚动方块是中灰色。你指定的
颜色可以通过色彩化来套用。
要完全清除目前的颜色，可以在 Javascript 中将其设定为 null。
 
范例
<scrollbar>
<thumbColor>#333366</thumbColor>
</scrollbar>
myScrollbar.thumbColor = "#333366";
myScrollbar.thumbColor = null;
 
可用性
适用于 3.0 版或更高版本。
 
 
vAlign 控制对象的垂直对齐
说明
对象的 vAlign 属性可以定义它的位置与它的 vOffset 之间的垂直关系。例如，将会显示 bottom
对齐的图片，以使其底部边缘显示在 vOffset 上。如果未指定此标签，默认值则为 "top"。
有效数值包括："top"、"bottom" 或 "center"。
 
JavaScript
myObjectName.vAlign
 
范例
<scrollbar>
<vAlign>bottom</vAlign>
</scrollbar>
myScrollbar.vAlign = "bottom";
 
可用性
适用于 3.0 版或更高版本。
 
value滚动条的当前数值
说明
数值属性中包含滚动条的目前数值。也可以使用它来将数值设定为滚动条的最小与最大数值之间
的某个数值。如果你指定的数值小于最小数值或大于最大数值，数值就会固定为那些数值。
 
JavaScript
myObjectName.value
 
范例

<scrollbar>
<min>-100</min>
<max>100</max>
<value>0</value>
</scrollbar>
myScrollbar.value = 10;
 
可用性
适用于 3.0 版或更高版本。
 
visible 控制图片可见与否
说明
可以设定图片的可见属性，可分别将其设定为 true 或 false 来显示或隐藏图片。这可以让你隐
藏对象，而不会影响它们的透明度，或无须存放目前的透明度以便稍后还原之用。如未指定，任何对
象的默认可见与否都是 true。
 
JavaScript
myObjectName.visible
 
范例
<scrollbar>
<visible>false</visible>
</scrollbar>
myScrollbar.visible = true;
 
可用性
适用于 3.0 版或更高版本。
 
vOffset 图片的垂直位移
说明
vOffset 属性以0,0（父视图的左上角）作为基点为对象定义垂直 (从上到下) 的位移。指定的
数值越大，对象就画得越往下。
 
JavaScript
object.vOffset
 
范例
<scrollbar>
<vOffset>20</vOffset>
</scrollbar>
 
可用性

适用于 3.0 版或更高版本。
width 对象的宽度
说明
width 属性可以控制对象的水平尺寸。对于垂直滚动条来说，你无须指定宽度。滚动条图片的大
小将会决定它。一般来讲，你不应该指定宽度，而应该询问滚动条其宽度是多少，以配置 接口。这样
将会使你未来无法改变滚动条的外观。很明显地，对于水平滚动条来说，必须将宽度设定为 接口所要
求的任何高度。
 
JavaScript
myObjectName.width
 
范例
<scrollbar>
<width>300</width>
</scrollbar>
myScrollbar.width = 200;
 
可用性
适用于 3.0 版或更高版本。
 
window 此对象所属的窗口。
说明
可以在 XML 中指定对象名称或在 JavaScript 中指定其变量来指定对象所属的窗口。如果你没有
指定窗口，对象就会自动附加到在 Widget 的 XML 说明中所找到的第一个窗口内。
 
JavaScript
myObjectName.window
 
范例
<window name="fred" width="100" height="100"/>
<scrollbar>
<window>fred</window>
</scrollbar>
// 或在程序代码中
var myWind = new Window();
myScrollbar.window = myWind;
// 也可以在结构式中指定它
var myFrame = new ScrollBar( myWind );
 
可用性
适用于 3.0 版或更高版本。

zOrder 对象的显示顺序
说明
zOrder 属性可以定义对象的显示顺序。zOrder 较高的对象会画在 zOrder 较低的对象之上。一
般情况下，zOrder 是由在 XML 文件中定义对象的顺序来决定的，较早显示的对象在较晚显示的对象
的下方，不过它也可以在 runtime 中使用 JavaScript 来操纵。
 
JavaScript
myObjectName.zOrder
 
范例
<scrollbar>
<zOrder>10</zOrder>
</scrollbar>
myScrollbar.zOrder = customZOrder++;
 
可用性
适用于 3.0 版或更高版本。
 
 
<security> 指定对象的安全属性
属性 (Attributes)
Api
 
说明
安全标签会通知引擎 Widget 可以做及不可以做的事情。它可以用来强迫行为保护 Widget 中的
用户不会不时到其范围之外。
 
可用性
适用于 3.1 版或更高版本。
api 此 Widget 要远程调用的 Yahoo! API。
说明
api 元素可以对引擎识别 Widget 要存取的 API。当 Widget 第一次尝试登陆到他们的 Yahoo! 账
号时，此清单会显示给用户。只有在这些 <api> 项目中列出的 API 才能够取得传送给它们的用户的
Yahoo! 证书。
大多数 API 都为引擎所知，因此它们将会在显示出来的安全对话框中自动显示出可供人阅读的名
称。如果新增了引擎不了解的 API，可以指定能够告知我们将会显示在对话框中的内容的 name 属性。
如果我们使用你指定的名称，我们也会将你指定的主机放在对话框中，以使用户能够准确了解正在存
取的内容。如果未指定名称，主机将会显示出来。
 

范例
<security>
 <!-- 引擎知道的记事本 API -->
 <api>api.notepad.yahoo.com</api>
 <!-- 以下的一些未来 API -->
 <api name="Yahoo! Foozball">foozball.yahoo.com</api>
</security>
可用性
适用于 3.1 版或更高版本。
 
<shadow> 指定对象的阴影参数
属性 (Attributes)
color/colour
hOffset
opacity
vOffset
 
说明
阴影元素目前只能在关于方块文字项目中使用。它可以让将项目上的实心阴影设定为某种颜色及
透明度。你指定的 h 与 vOffsets 是与你设定阴影的对象之间的位移距离 (目前，文字)。
 
可用性
适用于 2.1 版或更高版本。
color/colour 阴影的颜色
说明
指定要更改类型的阴影的颜色。
 
范例
<shadow color="#333333"/>
 
可用性
适用于 2.1 版或更高版本。
hOffset 阴影的水平位移
 
说明
指定与要更改类型的阴影的原始对象之间的水平位移。数值为 1 表示阴影往对象右方位移 1 个
像素。

范例
<shadow hOffset="1"/>
 
可用性
适用于 2.1 版或更高版本。
 
opacity 阴影的透明度
说明
指定从 0 到 255 之间的阴影的透明度，0 表示完全透明，255 表示完全不透明。
 
范例
<shadow opacity="255"/>
 
可用性
适用于 2.1 版或更高版本。
vOffset 阴影的垂直位移
说明
指定与要更改类型的阴影的原始对象之间的垂直位移距离。数值为 1 表示阴影往对象下方位移 1
个像素。
 
范例
<shadow vOffset="1"/>
 
可用性
适用于 2.1 版或更高版本。
 
<text> 定义文字及关联默认属性的标签
属性 (Attributes)
alignment
bgColor
bgOpacity
color
contextMenuItems
data
font
height
hAlign
hOffset

name
onContextMenu
onDragDrop
onDragEnter
onDragExit
onKeyUp
onKeyDown
onMouseDown
onMouseEnter
onMouseExit
onMouseMove
onMouseUp
onMultiClick
opacity
shadow
size
style
truncation
visible
vOffset
width
window
zOrder
 
说明
XML 文件中的 text 标签可以为 Widget 中的静态文字定义初始位置及鼠标事件代码。
文字也可以通过 JavaScript 引擎动态建立及清除。如果你正在建立列出了不确定项目数的
Widget，它将会很有用。
当你建立了多个具有相同名称的动态对象时，只有最后建立的一个对象将会通过 JavaScript 接
收属性改变事件。因此你应该确定你调用的是每个动态对象的唯一名称，以使它们能够被正确应用 (使
用 JavaScript 数组通常是达成此一目标的好方法)。关于此项作业的更进一步信息，请参见它在我们
的 Stock Ticker Widget 中的使用方式。
可以在建立动态对象时使用 JavaScript delete 指令来删除它。
 
JavaScript
newObjectName = new Text()
delete newObjectName
alignment 文字对齐的方向
说明
文字标签的对齐属性可以定义正在转译的文字的初始水平对齐。
有效数值包括：left、right 或 center。
范例
<text data="Example Text">
<alignment>right</alignment>

</text>
bgColor 文字的背景颜色
说明
设定文字的背景颜色。颜色会指定为浏览器样式 16 进位 RGB triplet。例如：
#FF0000
为红色。
请注意，此属性会与 bgOpacity 属性紧密地连结在一起 – 两者都应该设定以取得可以看见的结
果。
 
范例
<text data="Example Text">
<bgColor>#FFFFFF</bgColor>
<bgOpacity>150</bgOpacity>
</text>
 
bgOpacity 文字背景的透明度
说明
设定文字的背景的透明度。透明度会指定为 0 到 255 之间的数字。
请注意，此属性会与 bgColor 属性紧密地连结在一起 – 两者都应该设定以取得可以看见的结果。
 
范例
<text data="Example Text">
<bgColor>#FFFFFF</bgColor>
<bgOpacity>150</bgOpacity>
</text>
 
color文字的颜色
说明
设定文字的颜色。颜色会指定为浏览器样式 16 进位 RGB triplet。例如：
#FF0000
为红色。
 
范例
<text data="Example Text">
<color>#F42DA6</color>
</text>
 

contextMenuItems菜单项目的数组。
说明
可以通过将 contextMenuItems 加到 文字中，来将项目加到当用户在 Widget 上点击鼠标右键时
所显示的标准菜单中。实际上，此标签对于 image、textArea 以及 window 对象都有效。也可以在
onContextMenu 标签上指定要执行的某些 JavaScript 来动态地建立 内容项目 (关于更进一步信息，
请参见 onContextMenu)。
可以包含 menuItem 对象的数组来指定 项目。关于它们的更进一步信息，请参见有关 menuItem 的
小节说明。
 
JavaScript
myObjectName.contextMenuItems
 
范例
<text>
...
 <contextMenuItems>
<menuItem title="Test" onSelect="beep();"/>
<menuItem title="Another Test">
 <onSelect>alert( 'hello' );</onSelect>
</menuItem>
</contextMenuItems>
</text>
请参见 onContextMenu 小节中有关在 JavaScript 中建立菜单的范例。
 
可用性
适用于 2.0 版或更高版本。
data显示的文字
说明
要显示的文字。请注意，在显示之前，文字中的任何新行或换行符号都会转换为空格。
 
范例
<text>
 <data>Example Text</data>
</text>
font文字显示时所使用的字体
说明
转译文字时将会使用的字体名称。如果找不到指定的字体，将会使用默认的「系统字体」。请使用
逗号来分隔多个字体名称以指定 fallbacks (当在用户系统上找不到之前的字体时，在事件中使用的
字体)。

范例
<text data="Example Text">
<font>Palatino</font>
</text>
text1.font = "Monaco, Courier";
 
hAlign 控制文字的水平对齐。
说明
这是对齐标签的同义字。请参见该标签的说明来了解详细信息。
 
可用性
适用于 2.0 版或更高版本。
 
height 建立的文字的高度
说明
height 属性可以控制文字的垂直尺寸。如果未指定任何尺寸，对象将会占用正好足够的空间以放
置文字 (以指定的字体、大小等来转译)。你通常无须指定文字的 height。
 
JavaScript
myObjectName.height
 
范例
<text data="Example Text">
<height>30</height>
</text>
myLabel.height = 30;
 
hOffset 文字的水平位移
说明
文字标签的 hOffset 属性以0,0（父视图的左上角）作为基点为文字定义水平 (从左到右) 的位
移。指定的数值越大，文字就会画得越往右。
 
JavaScript
myObjectName.hOffset
 
范例
<text data="Example Text">
<hOffset>30</hOffset>
</text>

 
name 文字的名称
说明
text 标签的 name 属性可以由 JavaScript 操纵。由于名称要用来在程序代码中作应用，因此它
不可以包含任何空格或非 ASCII 字符。
一经指定，对象名称将无法改变。
当通过 JavaScript 建立动态对象时，可以使用变量的名称来代表对象的新名称。
 
JavaScript
newObjectName = new Image()
 
范例
<text data="Example Text">
<name>myText</name>
/text>
myText.hOffset = 22;
 
onContextMenu显示菜单时调用
说明
为 Widget 指定加到标准菜单中的菜单项目，最简单的方法就是在 XML 中使用 contextMenuItems
标签。但是，对于那些需要动态建立其项目的 Widget 来说，onContextMenu 句柄是你最好的工具。
当即将要显示菜单时，在某些视图响应之前，它会按照视图顺序从前到后在鼠标底下针对所有元素调
用。处理此情况时，你只须建立菜单项目，并将 contextMenuItems 属性设定为项目的数组即可。
 
JavaScript
myText.onContextMenu
 
范例
<onContextMenu>
var items = new Array();
items[0] = new MenuItem();
items[0].title = "This is the title";
items[0].enabled = false;
items[0].checked = true;
items[0].onSelect = "alert( 'you chose it!' );";
items[1] = new MenuItem();
items[1].title = "This is the second title";
items[1].onSelect = "beep();";
myText.contextMenuItems = items;
</onContextMenu>
可用性

JavaScript
myObjectName.onDragDrop
 
范例
<text data="Drop Stuff Here">
<name>dropper</name>
<onDragDrop>
 if (system.event.data[0] == "filenames")
 {
processDroppedFiles(system.event.data);
}
</onDragDrop>
</text>
<text data="Drop Stuff Here">
<onDragDrop>dragCode.js</onDragDrop>
</text>
dropper.onDragDrop = "handleDragDrop();";
onDragEnter 将项目拖曳到对象中时被调用
说明
text 标签的 onDragEnter 属性是当用户已将项目从其它应用程序中拖曳到对象中时将被调用的
JavaScript 函数。在拖放项目之前会发生此种情况 (实际上它可能不会被拖放，因为用户的想法会改
变)。
这可以用来触发对象的外观发生变化，以指示用户如果拖放对象，将会接受还是拒绝被拖曳的对
象。有关拖曳项目的信息，可查阅 system.event.data (如需详细信息，请参见 onDragDrop)。
 
JavaScript
myObjectName.onDragEnter
 
范例
<text data="Drop Stuff Here">
<name>dropper</name>
<onDragEnter>
适用于 2.0 版或更高版本。
 
onDragDrop 将某些项目放到对象上时调用此代码
说明
将文件、URL 或字符串从其它应用程序 (如 Finder) 中拖曳出来，并放到对象上时，onDragDrop
触发器便会触发。
在 onDragDrop 中，动作对象可以存取 system.event.data 来查看拖放的内容。这是字符串的数
组，其中第一个元素会告诉你哪些项目已被拖曳：filenames、urls 或 string。数组的其它元素是被
拖放的项目。
 

highlightDropTarget(dropper);
</onDragEnter>
</text>
well.onDragEnter = "highlightDropTarget(well);";
 
onDragExit 将项目拖曳到对象外时被调用
说明
text 标签的 onDragExit 属性是当用户已将项目从其它应用程序中拖曳到对象中然后再拖曳出去
时将被调用的 JavaScript 函数。
对于取消已在 onDragEnter 中执行的项目来说，这是很有用的。
 
JavaScript
myObjectName.onDragExit
 
范例
<text data="Drop Stuff Here">
<name>dropper</name>
<onDragExit>
unhighlightDropTarget(dropper);
</onDragExit>
</text>
dropper.onDragExit = "unhighlightDropTarget(dropper);";
 
onMouseDown 在对象上按下鼠标按键时调用
说明
text 标签的 onMouseDown 属性是当用户在对象中按下鼠标按键时将被调用的 JavaScript 函数。
对于根据按下的状态触发对象的外观发生变化来说，这是很有用的。
 
JavaScript
myObjectName.onMouseDown
范例
<text data="Example Text">
<name>myLabel</name>
<onMouseDown>
myLabel.color = "#FF0000";
</onMouseDown>
</text>
<text data="Example Text" name="myLabel">
<onMouseDown>labelCode.js</onMouseDown>
</text>
myLabel.onMouseDown = "doLabelHighlight(myLabel);";

 
onMouseEnter 当鼠标移动到对象中时被调用
说明
text 标签的 onMouseEnter 属性是当用户在对象中移动光标时将被调用的 JavaScript 函数。
对于根据滚动状态来触发对象的外观发生变化，或对于除非你在 Widget 上停留，否则就会显示
的隐藏对象来说，它是很有用的。
 
JavaScript
myObjectName.onMouseEnter
 
范例
<text data="Example Text">
<name>myLabel</name>
<onMouseEnter>
myLabel.color = "#EEEEEE";
</onMouseEnter>
</text>
myLabel.onMouseEnter = "handleMouseEnter(myLabel);";
 
onMouseExit 当鼠标移动到对象外时被调用
说明
text 标签的 onMouseExit 属性是当用户将光标从对象中移动到对象外时将被调用的 JavaScript
函数。
对于根据滚动状态来触发对象的外观发生变化，或对于除非你在 Widget 中停留，否则就会重新
隐藏已经隐藏的对象来说，它是很有用的。
 
JavaScript
myObjectName.onMouseExit
 
范例
<text data="Example Text">
<name>myLabel</name>
<onMouseExit>
myLabel.color = "#FFFFFF";
</onMouseExit>
</text>
myLabel.onMouseExit = "handleMouseExit(myLabel);";
 

onMouseMove 当鼠标在对象中移动时被调用
说明
text 标签的 onMouseMove 属性是当用户将鼠标光标拖曳到对象的范围内时将被调用的
JavaScript 函数。目前的鼠标位置可以在 system.event 对象中使用。
这可以用于在 Widget 周围移动对象。iTunes Remote Widget 中的音量滚动条也可以使用此动作
来内建。
 
JavaScript
myObjectName.onMouseMove
 
范例
<text data="Example Text">
<name>myLabel</name>
<onMouseMove>
 print(system.event.x + ", " + system.event.y);
</onMouseMove>
</text>
 
myLabel.onMouseMove = "handleMouseMove(myLabel);";
 
onMouseUp 在对象中放开鼠标按键时被调用
说明
text 标签的 onMouseUp 属性是当用户在对象中按下鼠标按键之后再放开它时将被调用的
JavaScript 函数。
对于根据按下的状态触发对象的外观发生变化来说，这是很有用的。
请注意，即使放开鼠标按键时鼠标不在对象内，onMouseUp 也会触发。要建立拥有正确鼠标事件
的按钮，必须使用所有四个鼠标事件句柄，以传送鼠标的状态及其交集状态 (关于此项目的范例，请
参见随附的 Calendar Widget)。
 
JavaScript
myObjectName.onMouseUp
 
范例
<text data="Example Text">
<name>myLabel</name>
<onMouseUp>
myLabel.color = "#FFFFFF";
</onMouseUp>
</text>
myLabel.onMouseUp = 'handleOnMouseUp(myLabel);';
 

onMultiClick 多次按下鼠标按键时调用
说明
可以使用 onMultiClick 句柄轻松设陷按两下 (或按三下等)。此句柄可以在图片、文字、文字标
签与窗口对象上设定。无论何时调用 onMultiClick，都可以检查 system.event.clickCount 以查看
数值为何。它将永远是 2 (针对按两下) 或更大。
也可以在 onMouseUp 句柄中检查此 system.event.clickCount，以及替代使用 onMultiClick。
但是，使用 onMultiClick 的好处在于它不会像 onMouseUp 一样干扰窗口拖曳的方式，也就是说，文
字项目上的往上移动鼠标句柄将会在你点击该项目时防止窗口被拖曳。如果 文字项目只需要响应按多
下，就可以使用 onMultiClick，而且 Widget 将仍然能够像平常一样拖曳。
 
<onMultiClick>
if ( system.event.clickCount == 2 )
alert( "Double Click!" );
</onMultiClick>
 
可用性
适用于 2.0 版或更高版本。
 
opacity 文字的透明度
说明
opacity 属性可以让你指定 0 到 255 之间的某个数值，它可以控制文字转译时所使用的 alpha 数
值。透明度为 0 表示完全透明 (不可见)，而且有防止对象响应鼠标事件的反效果。数值 255 会将文
字转译为 100% 不透明。
 
范例
<text data="Example Text">
<name>myLabel</name>
<opacity>128</opacity>
</text>
myLabel.opacity = 33;
 
scrolling 动态滚动的方向与类型
说明
scrolling 属性会取用 off (默认值)、left、right、autoLeft 或 autoRight 的数值。如已设
定，对象中的文字会以指定的方向持续滚动，消失之后会在另一端重新出现。
只有文字太大而无法显示在指定标签中时，"auto" 变量才会滚动 (这是在较小的空间内显示较长
文字时最常使用的滚动用法)。
 
范例
<text data="Example Text">

<name>myLabel</name>
<scrolling>autoLeft</scrolling>
</text>
myLabel.scrolling = "off";
 
shadow设定文字的阴影参数
说明
可以使用阴影属性来指定显示在文字下方的阴影。要清除阴影，只需将阴影属性设定为 null 即
可。阴影 XML 与在 <shadow> 一节中所说明的一样。
 
范例
<text data="Example Text">
<name>myLabel</name>
<shadow hOffset="1" vOffset="1" color="#000000"/>
</text>
var s = new Shadow();
s.hOffset = 1;
s.vOffset = 1;
s.color = "#000000";
myLabel.shadow = s;
myLabel2.shadow = s;
 
可用性
适用于 3.0 版或更高版本。
size 文字的字号
说明
文字的级数大小。
 
范例
<text data="Example Text">
<name>myLabel</name>
<size>22</size>
</text>
myLabel.size = 33;
 
style 显示的文字样式
说明
转译文字的样式。样式可以是以下任何一种组合：

italic、bold、narrow、expanded、condensed、smallcap、poster、compressed、fixed
 
例如：
textObject.style = "bold;italic";
会要求在 font 属性中命名的字体的粗体、斜体字体样式。
请注意，字体必须具有要求的字体样式，否则样式将会遭到忽略。大多数字体都只支持二或三种字体
样式。
Windows 注意事项：只有「粗体」与「斜体」是有效样式。
 
范例
<text data="Example Text">
<name>myLabel</name>
<style>bold</style>
</text>
myLabel.style = 'italic';
 
truncation 指定是否截断含有省略符号的文字。
说明
正常情况下，文字将在不发生任何裁断的情况下显示。如果没有显示完整文字的空间，它将会被
裁掉。此标签可以让使用省略符号聪明地裁断它，而不必指定文字的宽度对于文字来说是否太小。
只有当存在针对文字项目指定的宽度时、文字项目比宽度长而且未指定滚动属性时，此标签才会
生效。有效数值包括 "none"、"center" 及 "end"。
 
范例
<text data="Example Text">
<name>myLabel</name>
<width>50</width>
<truncation>end</truncation>
</text>
myLabel.truncation = "none";
 
可用性
适用于 2.1 版或更高版本。"center" 截断仅适用于 3.0 版或更高版本。
tooltip 文字的工具提示
说明
tooltip 属性可以定义当鼠标光标停留在 text 对象上时显示在popup式工具提示窗口中的文字。
 
JavaScript
object.tooltip
 
范例
<text data="Example Text">

<tooltip>Example tooltip</tooltip>
</text>
visible 控制文字可见与否
说明
可以设定文字的可见属性，可分别将其设定为 true 或 false 来显示或隐藏文字。这可以让你隐
藏对象，而不会影响它们的透明度，或无须存放目前的透明度以便稍后还原之用。如未指定，任何对
象的默认可见与否都是 true。
 
JavaScript
myObjectName.visible
 
范例
<text data="Example Text">
<visible>false</visible>
</text>
myText.visible = true;
 
可用性
适用于 3.0 版或更高版本。
 
vOffset 文字的垂直位移
说明
text 标签的 vOffset 属性以0,0（父视图的左上角）作为基点为文字定义垂直 (从上到下) 的
位移。指定的数值越大，文字就画得越往下。
 
JavaScript
object.vOffset
 
范例
<text data="Example Text">
<vOffset>20</vOffset>
</text>
width 文字的宽度
说明
width 属性可以控制文字的水平尺寸。如果未指定任何尺寸，对象将会占用正好足够的空间以放
置文字 (以指定的字体、大小等来转译)。有时，它可以用来在使用 scrolling 属性时指定文字的宽
度。

JavaScript
myObjectName.width
 
范例
<text data="Example Text">
<width>30</width>
</text>
myLabel.width = 30;
 
window 文字所属的窗口。
说明
可以在 XML 中指定文字名称或在 JavaScript 中指定其变量来指定文字所属的窗口。如果你没有
指定窗口，对象就会自动附加到在 Widget 的 XML 说明中所找到的第一个窗口内。
 
JavaScript
myObjectName.window
 
范例
<window name="fred" width="100" height="100"/>
<text>
<window>fred</window>
</text>
// 或在程序代码中
var myWind = new Window();
myText.window = myWind;
// 也可以在结构式中指定它
var myText = new Image( myWind );
可用性
适用于 2.0 版或更高版本。
 
zOrder 文字的显示顺序
说明
text 标签的 zOrder 属性可以定义文字的显示顺序。zOrder 较高的对象会画在 zOrder 较低的
对象之上。一般情况下，zOrder 是由在 XML 文件中定义对象的顺序来决定的，较早显示的对象在较
晚显示的对象的下方，不过它也可以在 runtime 中使用 JavaScript 来操纵。
 
JavaScript
myObjectName.zOrder
 
范例

<text data="Example Text">
<zOrder>10</zOrder>
</text>
myLabel.zOrder = customZOrder++;
 
 
<textarea>定义 textarea 对象及默认属性的标签
属性 (Attributes)
alignment
bgColor
bgOpacity
color
columns
contextMenuItems
bgColor
bgOpacity
data
editable
font
height
hAlign
hOffset
lines
name
onContextMenu
onDragDrop
onDragEnter
onDragExit
onGainFocus
onKeyUp
onKeyDown
onKeyPress
onLoseFocus
onMouseDown
onMouseEnter
onMouseExit
onMouseUp
nMultiClick
opacity
secure
scrollbar
size
spellcheck

style
tooltip
visible
vAlign
vOffset
width
window
zOrder
 
说明
XML 文件中的 textarea 标签可以为 Widget 中的可编辑文字定义初始位置及鼠标事件代码。
textarea 对象也可以通过 JavaScript 引擎动态建立及清除。
当你建立了多个具有相同名称的动态对象时，只有最后建立的一个对象将会通过 JavaScript 接
收属性改变事件。因此你应该确定你调用的是每个动态对象的唯一名称，以使它们能够被正确应用 (使
用 JavaScript 数组通常是达成此一目标的好方法)。
可以在建立动态对象时使用 JavaScript delete 指令来删除它。
 
JavaScript
newObjectName = new TextArea()
delete newObjectName
alignment 对象的对齐方式
说明
textarea 标签的对齐属性可以定义对象的放置位置与其 hOffset 与 vOffset 之间的关系。
有效数值包括：left、right 或 center。
请注意，它并不会定义 textarea 中文字的对齐，而会定义 Widget 中的对象位置。left 是此属
性的最常用数值。
 
范例
<textarea data="Example Text">
<alignment>left</alignment>
</textarea>
 
bgColor textarea 对象的背景颜色
说明
设定 textarea 对象的背景颜色。颜色会指定为浏览器样式 16 进位 RGB triplet。例如：
#FF0000
为红色。
请注意，此属性会与 bgOpacity 属性紧密地连结在一起 – 两者都应该设定以取得可以看见的结
果。
 
范例
<textarea data="Example Text">

<bgColor>#FFFFFF</bgColor>
<bgOpacity>150</bgOpacity>
</textarea>
 
bgOpacity textarea 对象背景的透明度
说明
设定 textarea 对象的背景的透明度。透明度会指定为 0 到 255 之间的数字。
请注意，此属性会与 bgColor 属性紧密地连结在一起 – 两者都应该设定以取得可以看见的结果。
 
范例
<textarea data="Example Text">
<bgColor>#FFFFFF</bgColor>
<bgOpacity>150</bgOpacity>
</textarea>
 
color 文字颜色
说明
设定文字的颜色。颜色会指定为浏览器样式 16 进位 RGB triplet。例如：
#00FF00
为绿色。
如果将 color 与 bgColor 设定为相同的数值，将无法看到文字。
范例
<textarea data="Example Text">
<color>#F42DA6</color>
</textarea>
 
columns 对象的栏数
说明
除了为 textarea 对象提供 width 与 height 之外，其大小也可以通过目前字体中的文字
columns 与 lines 数来指定。
请注意，使用调和间距字体将会使栏数成为近似值。
 
范例
<textarea>
<columns>40</columns>
<lines>10</lines>
</textarea>
 

contextMenuItems 指定菜单项目的数组。
说明
可以通过将 contextMenuItems 加到 文字标签中，来将项目加到用户在 Widget 上点击鼠标右键
时所显示的标准菜单中。实际上，此标签对于图片、文字以及窗口对象都有效。也可以在 onContextMenu
标签上指定要执行的某些 JavaScript 来动态地建立 内容项目 (关于更进一步信息，请参见
onContextMenu)。
可以包含 menuItem 对象的数组来指定 项目。关于它们的更进一步信息，请参见有关 menuItem 的
小节说明。
 
JavaScript
myObjectName.contextMenuItems
 
范例
<textarea>
...
<contextMenuItems>
 <menuItem title="Test" onSelect="beep();"/>
<menuItem title="Another Test">
<onSelect>alert( 'hello' );</onSelect>
</menuItem>
</contextMenuItems>
</textarea>
请参见 onContextMenu 小节中有关在 JavaScript 中建立菜单的范例。
 
可用性
适用于 2.0 版或更高版本。
 
data textarea 对象包含的文字
说明
要编辑的文字。此属性为选用属性。如遭忽略，将会为用户显示空白文字输入字段。
 
范例
<textarea>
 <data>Example Text</data>
</textarea>
 
editable 设定文字是否可以编辑
说明
将 editable 设定为 false 可以使 textarea 只显示。
 

范例
<textarea data="Example Text">
<editable>false</editable>
</textarea>
ta1.editable = true;
 
font textarea 使用的字体
说明
转译文字时将会使用的字体名称。如果找不到指定的字体，将会使用默认的「系统字体」。请使用
逗号来分隔多个字体名称以指定 fallbacks (当在用户系统上找不到之前的字体时，在事件中使用的
字体)。
 
范例
<textarea data="Example Text">
<font>Palatino</font>
</textarea>
ta1.font = "Palatino, Times";
 
 
hAlign 控制 textarea 对象的水平对齐。
说明
这是对齐标签的同义字。请参见该标签的说明来了解详细信息。
 
可用性
适用于 2.0 版或更高版本。
 
Height textarea 对象的高度
说明
height 属性可以控制 textarea 对象的垂直尺寸。
 
JavaScript
myObjectName.height
 
范例
<textarea data="Example Text">
<height>30</height>
</textarea>
ta1.height = 30;
 

 
hOffsettextarea 对象的水平位移
说明
文字标签的 hOffset 属性以0,0（父视图的左上角）作为基点为文字定义水平 (从左到右) 的位
移。指定的数值越大，文字就会画得越往右。
 
JavaScript
myObjectName.hOffset
 
范例
<textarea data="Example Text">
<hOffset>30</hOffset>
</textarea>
lines 对象的栏数
说明
除了为 textarea 对象提供 width 与 height 之外，其大小也可以通过目前字体中的文字
columns 与 lines 数来指定。
为 lines 指定数值 1 可以稍微改变 textarea 对象的行为。当打字时，如果文字到达了对象的
边缘，文字并不会换行，而是会往旁边滚动。
 
范例
<textarea>
<columns>40</columns>
<lines>10</lines>
</textarea>
 
Name textarea 对象的名称
说明
由于名称要用来在程序代码中应用，因此它不可以包含任何空格或非 ASCII 字符。
一经指定，对象名称将无法改变。
 
当通过 JavaScript 建立动态对象时，可以使用变量的名称来代表对象的新名称。
 
JavaScript
newObjectName = new TextArea()
 
范例
<textarea data="Example Text">

<name>myText</name>
</textarea>
myText.hOffset = 22;
 
onContextMenu 显示菜单时调用
说明
要为 Widget 指定被加到标准菜单中的菜单项目，最简单的方法就是在 XML 中使用
contextMenuItems 标签。但是，对于那些需要动态建立其项目的 Widget 来说，onContextMenu 句柄
是你最好的工具。当即将要显示菜单时，在某些视图响应之前，它会按照视图顺序从前到后在鼠标底
下针对所有元素调用。处理此情况时，你只须建立菜单项目，并将 contextMenuItems 属性设定为项
目的数组即可。
 
JavaScript
myTextArea.onContextMenu
 
范例
<onContextMenu>
var items = new Array();
items[0] = new MenuItem();
items[0].title = "This is the title";
items[0].enabled = false;
items[0].checked = true;
items[0].onSelect = "alert( 'you chose it!' );";
items[1] = new MenuItem();
items[1].title = "This is the second title";
items[1].onSelect = "beep();";
myTextArea.contextMenuItems = items;
</onContextMenu>
onDragDrop 将某些项目放到对象上时，便调用此代码
说明
将文件、URL 或字符串从其它应用程序 (如 Finder) 中拖曳出来，并放到对象上时，onDragDrop
触发器便会触发。
在 "onDragDrop" 中，动作对象可以存取 system.event.data 来查看拖放的内容。这是字符串的
数组，其中第一个元素会告诉你哪些项目已被拖曳：filenames、urls 或 string。数组的其它元素是
被拖放的项目。
 
JavaScript
myObjectName.onDragDrop
 
范例
<textarea data="Drop Stuff Here">

<name>dropper</name>
<onDragDrop>
 if (system.event.data[0] == "filenames")
{
dropper.data = runCommand("cat " +
system.event.data[1]);
}
</onDragDrop>
</textarea>
<textarea data="Drop Stuff Here">
<onDragDrop>dragCode.js</onDragDrop>
</textarea>
dropper.onDragDrop = "handleDragDrop();";
 
 
onDragEnter 将项目拖曳到对象中时被调用
说明
textarea 标签的 onDragEnter 属性是当用户已将项目从其它应用程序中拖曳到对象中时将被调
用的 JavaScript 函数。在拖放项目之前会发生此种情况 (实际上它可能不会被拖放，因为用户的想
法会改变)。
这可以用来触发对象的外观发生变化，以指示用户如果拖放对象，将会接受还是拒绝被拖曳的对
象。有关拖曳项目的信息，可查阅 system.event.data (如需详细信息，请参见 onDragDrop)。
 
JavaScript
myObjectName.onDragEnter
 
范例
<textarea data="Drop Stuff Here">
<name>dropper</name>
<onDragEnter>
highlightDropTarget(dropper);
</onDragEnter>
</textarea>
well.onDragEnter = "highlightDropTarget(well);";
 
onDragExit 将项目拖曳到对象外时被调用
说明
textarea 标签的 onDragExit 属性是当用户已将项目从其它应用程序中拖曳到对象中然后再拖出
去时将被调用的 JavaScript 函数。
对于取消已在 onDragEnter 中执行的项目来说，这是很有用的。

JavaScript
myObjectName.onDragExit
 
范例
<textarea data="Drop Stuff Here">
<name>dropper</name>
<onDragExit>
unhighlightDropTarget(dropper);
</onDragExit>
</textarea>
dropper.onDragExit = "unhighlightDropTarget(dropper);";
 
onGainFocus 当 textarea 取得键盘焦点时调用
说明
当文字标签通过对于 textarea.focus() 的调用取得键盘焦点，或当用户点击文字标签时，便会
调用此属性。可以使用它来显示焦点装饰以指出焦点。只有可编辑的文字标签才可以取得键盘焦点，
而且就其本身而言，此动作将只能针对可编辑的文字标签调用。
 
JavaScript
NewObjectName.onGainFocus
 
范例
<textarea data="Type Stuff Here">
<name>typomatic</name>
<onGainFocus>
print("I am the focus!");
</onGainFocus>
</textarea>
typomatic.onGainFocus = "print( 'focus gained!' );";
 
onKeyDown 按下按键时调用的程序代码
说明
当按下按键且鼠标光标在 textarea 对象的范围之内时所要执行的程序代码会以 onKeyDown 属性
来指定。请注意，针对 textarea 将按键码附加到 onKeyPress 动作上通常是最好的处理方法，因为
这才是用户期待的方法。
 
JavaScript
NewObjectName.onKeyDown
 
范例
<textarea data="Type Stuff Here">

<name>typomatic</name>
<onKeyDown>
print(system.event.key);
</onKeyDown>
</textarea>
typomatic.onKeyDown = "keypressed = true";
 
onKeyPress 当按下按键且 textarea 为焦点时所调用
说明
textarea 标签的 onKeyPress 属性是当用户按下会影响对象的按键时，将被调用的 JavaScript
函数 (除非采取了步骤，否则请参见以下内容)。
这对于执行文字输入的验证来说很有用。一般情况下，按下的任何按键都是由系统以及对于
textarea 所做的适当改变 (新增字符、删除文字等) 来处理的，可以通过调用会导致按键遭到忽略的
textarea 方法 rejectKeyPress() 来覆盖此行为 (它始终可以在 system.event.key 中使用)。
 
JavaScript
myObjectName.onKeyPress
 
范例
<textarea>
<name>ta1</name>
<onKeyPress>
// 将输入转换为大写
var key = system.event.key;
if (key.charCodeAt(0) &gt;= "A".charCodeAt(0) &&
 key.charCodeAt(0) &lt;= "z".charCodeAt(0))
 {
// 告诉文字标签忽略此 keyPress ta1.rejectKeyPress();
// 附加按下按键的大写副本
ta1.replaceSelection(key.toUpperCase());
}
</onKeyPress>
</textarea>
 
<textarea data="Example Text" name="ta1">
<onKeyPress>textareaCode.js</onKeyPress>
</textarea>
ta1.onKeyPress= "doProcessKeys(ta1);";
 
onKeyUp 放开按键时启动的程序代码
说明
当按下按键且鼠标光标在 textarea 对象的范围之内时所要执行的程序代码会以 onKeyUp 属性来

指定 (请注意在 textarea 中处理按键动作的最好方式通常是 onKeyPress)。
 
JavaScript
NewObjectName.onKeyUp
 
范例
<textarea data="Type Stuff Here">
<name>typomatic</name>
<onKeyUp>
print(system.event.key);
</onKeyUp>
</textarea>
typomatic.onKeyUp = "keypressed = true";
 
onLoseFocus 当 textarea 失去焦点时调用
说明
当之前通过 focus() 聚焦的文字标签失去了它的焦点时，便会调用此属性。可以使用它来清除你
可能在文字标签周围显示的用来指示焦点的焦点装饰。只有可编辑的文字标签才可以取得键盘焦点，
而且就其本身而言，此动作将只能针对可编辑的文字标签调用。
JavaScript
NewObjectName.onLoseFocus
范例
<textarea data="Type Stuff Here">
<name>typomatic</name>
<onLoseFocus>
print("I lost focus!");
</onLoseFocus>
</textarea>
typomatic.onLoseFocus = "print( 'focus lost!' );";
 
onMouseDown在对象上按下鼠标按键时调用
说明
textarea 标签的 onMouseDown 属性是当用户在对象中按下鼠标按键时将被调用的 JavaScript
函数。
由于鼠标是用来移动插入点、选择文字等的，因此，在 textarea 对象上指定鼠标动作时，请务
必小心。
 
JavaScript
myObjectName.onMouseDown
 
范例
<textarea data="Example Text">

<name>ta1</name>
<onMouseDown>
ta1.color = "#FF0000";
</onMouseDown>
</textarea>
<textarea data="Example Text" name="ta1">
<onKeyPress>textareaCode.js</onKeyPress>
</textarea>
ta1.onMouseDown = "doHighlight(ta1);";
 
onMouseEnter 当鼠标移动到对象中时被调用
说明
text 标签的 onMouseEnter 属性是当用户在对象中移动光标时将被调用的 JavaScript 函数。
由于鼠标是用来移动插入点、选择文字等的，因此，在 textarea 对象上指定鼠标动作时，请务
必小心。
 
JavaScript
myObjectName.onMouseEnter
 
范例
<textarea data="Example Text">
<name>ta1</name>
<onMouseEnter>
ta1.color = "#EEEEEE";
</onMouseEnter>
</textarea>
ta1.onMouseEnter = "handleMouseEnter(ta1);";
 
onMouseExit 当鼠标移动到对象外时被调用
说明
text 标签的 onMouseExit 属性是当用户将光标从对象中移动到对象外时将被调用的 JavaScript
函数。
由于鼠标是用来移动插入点、选择文字等的，因此，在 textarea 对象上指定鼠标动作时，请务
必小心。
 
JavaScript
myObjectName.onMouseExit
 
范例
<textarea data="Example Text">
<name>ta1</name>
<onMouseExit>

ta1.color = "#FFFFFF";
</onMouseExit>
</textarea>
ta1.onMouseExit = "handleMouseExit(ta1);";
 
 
onMouseUp 在对象中放开鼠标按键时被调用
说明
text 标签的 onMouseUp 属性是当用户在对象中按下鼠标按键之后再放开它时将被调用的
JavaScript 函数。
由于鼠标是用来移动插入点、选择文字等的，因此，在 textarea 对象上指定鼠标动作时，请务
必小心。
请注意，即使放开鼠标按键时鼠标不在对象内，onMouseUp 也会触发。
 
JavaScript
myObjectName.onMouseUp
 
范例
<textarea data="Example Text">
<name>ta1</name>
<onMouseUp>
ta1.color = "#FFFFFF";
</onMouseUp>
</textarea>
ta1.onMouseUp = 'handleOnMouseUp(ta1);';
 
onMultiClick 多次按下鼠标按键时调用
说明
可以使用 onMultiClick 句柄轻松设陷按两下 (或按三下等)。此句柄可以在图片、文字、文字标
签与窗口对象上设定。无论何时调用 onMultiClick，都可以检查 system.event.clickCount 以查看
数值为何。它将永远是 2 或更大。
也可以在 onMouseUp 句柄中检查此 system.event.clickCount，以及替代使用 onMultiClick。
但是，使用 onMultiClick 的好处在于它不会像 onMouseUp 一样干扰窗口拖曳的方式，也就是说，
textarea 上的往上移动鼠标句柄将会在你点击该 textarea 时防止窗口被拖曳。如果 textarea 只
需要响应按多下，就可以使用 onMultiClick，而且 Widget 将仍然能够像平常一样拖曳。
<onMultiClick>
if ( system.event.clickCount == 2 )
alert( "Double Click!" );
</onMultiClick>
可用性
适用于 2.0 版或更高版本。

 
opacity 文字的透明度
说明
opacity 属性可以让你指定 0 到 255 之间的某个数值，它可以控制文字转译时所使用的 alpha 数
值。透明度为 0 表示完全透明 (不可见)，而且有防止对象响应鼠标事件的反效果。数值 255 会将文
字转译为 100% 不透明。
 
范例
<textarea data="Example Text">
<name>ta1</name>
<opacity>128</opacity>
</textarea>
ta1.opacity = 33;
secure
将 textarea 设定为显示圆点而不显示文字
 
说明
此属性可以用来仿真密码字段，用户在其中看不到正在键入的文字，而只能看到一系列圆点字符
(小圆圈)。这通常应占用一列文字。
 
范例
<textarea data = "hello!">
 <secure>true</secure>
</textarea>
可用性
适用于 2.1 版或更高版本。
 
Scrollbar textarea 上滚动条
说明
依照默认，textarea 将会显示垂直的滚动条。使用此属性可将其关闭。
 
范例
<textarea data="Example Text">
<scrollbar>false</scrollbar>
</textarea>
ta1.scrollbar = true;

size textarea 标签的字号
 
说明
textarea 对象的级数大小。
 
范例
<textarea data="Example Text">
<name>ta1</name>
<size>22</size>
</textarea>
ta1.size = 33;
 
 
spellcheck 控制 textarea 中的拼写检查
说明
依照默认，textarea 会在用户输入文字时提示拼写错误，可以使用此属性来关闭该功能。
 
范例
<textarea data="Example Text">
<spellcheck>false</spellcheck>
</textarea>
ta1.spellcheck = true;
 
style textarea 标签的字体样式
说明
转译文字的样式。样式可以是以下任何一种组合：
italic、bold、narrow、expanded、condensed、smallcap、poster、compressed、fixed
 
例如：
textAreaObject.style = "bold;italic";
会要求在 font 属性中命名的字体的粗体、斜体字体样式。
请注意，字体必须具有要求的字体样式，否则样式将会遭到忽略。大多数字体都只支持二或三种
字体样式。
 
范例
<textarea data="Example Text">
<name>ta1</name>
<style>bold</style>
</textarea>
ta1.style = 'italic';

thumbColor 滚动条滚动方块的颜色
说明
如果 文字标签指定了滚动条，thumbColor 属性则可用来控制滚动条滚动方块的色调。标准滚动
条的默认滚动方块是中灰色。你指定的颜色可以通过色彩化来套用。
要完全清除目前的颜色，可以在 Javascript 中将其设定为 null。
 
范例
<scrollbar>
<thumbColor>#333366</thumbColor>
</scrollbar>
myScrollbar.thumbColor = "#333366";
myScrollbar.thumbColor = null;
 
可用性
适用于 3.0 版或更高版本。目前仅适用于 Windows。
 
tooltip textarea 对象的工具提示
说明
tooltip 属性可以定义当鼠标光标停留在 textarea 上时显示在popup式工具提示窗口中的文字。
 
JavaScript
object.tooltip
 
范例
<textarea data="Example Text">
<tooltip>Example tooltip</tooltip>
</textarea>
visible 控制 textarea 对象可见与否
说明
可以设定 textarea 对象的可见属性，可分别将其设定为 true 或 false 来显示或隐藏文字。这
可以让你隐藏对象，而不会影响它们的透明度，或无须存放目前的透明度以便稍后还原之用。如未指
定，任何对象的默认可见与否都是 true。
 
JavaScript
myObjectName.visible
 
范例
<textarea data="Example Text">
<visible>false</visible>

</textarea>
myTextArea.visible = true;
 
可用性
适用于 3.0 版或更高版本。
 
vAlign 控制文字标签的垂直对齐
说明
文字标签的 vAlign 属性可以定义它的位置与它的 vOffset 之间的垂直关系。例如，具有 bottom
对齐的文字标签将会被显示，以使其底部边缘显示在 vOffset (请参见下面的内容)。如果未指定此标
签，默认值则为 top。
有效数值包括：top、bottom 或 center。
 
JavaScript
myObjectName.vAlign
 
范例
<textarea src="button.png">
<vAlign>bottom</vAlign>
</textarea>
myTextArea.vAlign = "bottom";
 
可用性
适用于 2.0 版或更高版本。
 
vOffset textarea 对象的垂直位移
说明
textarea 标签的 vOffset 属性以0,0（父视图的左上角）作为基点为文字定义垂直 (从上到下)
的位移。指定的数值越大，文字就画得越往下。
 
JavaScript
object.vOffset
 
范例
<textarea data="Example Text">
<vOffset>20</vOffset>
</textarea>
 

width textarea 对象的宽度
说明
width 属性可以控制 textarea 对象的水平尺寸。
 
JavaScript
myObjectName.width
 
范例
<textarea data="Example Text">
<width>30</width>
</textarea>
ta1.width = 30;
 
参见 columns
 
window textarea 所属的窗口。
说明
可以在 XML 中指定 textarea 的名称或在 JavaScript 中指定其变量来指定 textarea 所属的窗
口。如果你没有指定窗口，textarea 就会自动附加到在 Widget 的 XML 说明中所找到的第一个窗口。
 
JavaScript
myObjectName.window
 
范例
<window name="fred" width="100" height="100"/>
<textarea>
<window>fred</window>
</textarea>
// 或在程序代码中
var myWind = new Window();
myTextArea.window = myWind;
// 也可以在结构式中指定它
var myTextArea = new Image( myWind );
 
可用性
适用于 2.0 版或更高版本。
 
zOrder textarea 对象的显示顺序
说明
text 标签的 zOrder 属性可以定义文字的显示顺序。zOrder 较高的对象会画在 zOrder 较低的

对象之上。一般情况下，zOrder 是由在 XML 文件中定义对象的顺序来决定的，较早显示的对象在较
晚显示的对象的下方，不过它也可以在 runtime 中使用 JavaScript 来操纵。
 
JavaScript
myObjectName.zOrder
 
范例
<textarea data="Example Text">
<zOrder>10</zOrder>
</textarea>
ta1.zOrder = customZOrder++;
 
 
<timer>定义定时器的标签
属性 (Attributes)
interval
name
ticking
onTimerFired
 
方法
reset()
 
说明
定时器对象可以让你以固定的时间间隔 (例如每隔 5 秒) 来执行工作，或者也可以用来单纯在稍
后的时间单次触发。它们可以取代作用中的较旧 onTimer 触发器。它们可以让你建立全部以不同频率
执行的多个定时器。也可以在不删除它们的情况下开始与停止它们。
间隔时间无法保证一定精确。「合作」执行的定时器是指它们会在 Widget 并不忙于做其它事情时
触发。你不能在定时器中做高精准度的时间性动作。
 
可用性
适用于 2.0 版或更高版本。
interval
定时器触发的时间间隔，以秒为单位。它可以以浮点来表示，因此如果要定时器每半秒触发一次，
只需为此属性指定 0.5 即可。定时器每次触发时，它都会在 onTimerFired 属性中执行 Javascript。
 
JavaScript
object.interval
 
范例
<timer name="myTimer">

<interval>1.0</interval>
</timer>
myTimer.interval = 1.0;
 
可用性
适用于 2.0 版或更高版本。
name定时器的名称
说明
偏好设置标签的名称属性可以定义要在 Javascript 中建立的全局变量名称。由于名称要在程序
代码中应用，因此它不应包含任何空格或非 ASCII 字符。将名称用来建立对象时，应该将其视为无效。
 
范例
<timer name="my_timer"/>
// 稍后在 Javascript 中，可以应用该名称:
my_timer.interval = 10;
 
可用性
适用于 2.0 版或更高版本。
ticking
此属性可以让你分别将其设定为 true 与 false 来打开与关闭它。如果要停用一下定时器，只需
将 ticking 设定为 false 即可。然后，只需再将其设定为 true 即可再次开始触发。重新启动之后，
下一次触发的时间将是「现在」的时间加上时间间隔。因此，如果你有一个一秒定时器，它将会在将
ticking 设定为 true 之后每秒触发一次。
 
JavaScript
object.ticking
 
范例
<timer name="myTimer">
<ticking>false</ticking>
</timer>
myTimer.ticking = true;
 
可用性
适用于 2.0 版或更高版本。
onTimerFired 此属性中包含在定时器触发时执行的 Javascript
JavaScript
object.onTimerFired
 

范例
<timer name="myTimer"> <onTimerFired>alert( 'hello!' );</onTimerFired>
</timer>
 
myTimer.onTimerFired = "alert( 'fired!' );";
 
可用性
适用于 2.0 版或更高版本。
 
 
<widget>
属性 (Attributes)
author
company
copyright
debug
defaultTracking
image
minimumVersion
option
requiredPlatform
version
 
说明
XML 文件中最外层的范围是由 widget 标签定义的。这可以将组成 Widget 的所有对象集合起来。
在 3.0 版及更高版本中，widget 对象可以通过一个全局对象来存取，刚好它也叫做 'widget'。
目前所有属性都是只读的。
author 作者名称
可以为 Widget 提供这个选用的信息。在 3.0 版中，它可以用来显示在我们的「第一次执行」
安全对话框中，以让人们可以看到是谁编写了 Widget (以及 'company' 属性)。未来，这个信息也会
在接口的其它标签中使用，因此你最好提供作者与/或公司及著作权属性。
 
可用性
适用于 3.0 版或更高版本。
company 公司名称
可以为 Widget 提供这个选用的信息。在 3.0 版中，它可以用来显示在我们的「第一次执行」
安全对话框中，以让人们可以看到是哪个公司发布了 Widget 。未来，这个信息也会在接口的其它标
签中使用，因此你最好提供作者与/或公司及著作权属性。

 
 
可用性
适用于 3.0 版或更高版本。
 
copyright 指定 Widget 的著作权
可以为 Widget 提供这个选用的信息。未来，这个信息也会在接口的其它标签中使用，因此你最
好提供作者与/或公司及著作权属性。
 
可用性
适用于 3.0 版或更高版本。
 
 
debug 控制是否显示调试主控台
说明
如果需要启用或阻止调试输出，请将此标签加到 widget 标签内部。
<debug>errors</debug>
如果在 Widget 执行时发生错误，便会打开 Widget 调试信息。错误可以是 JavaScript 或 Widget
Engine runtime 信息。这是默认值。
<debug>on</debug>
当 Widget 打开时，便会打开 Widget 调试信息 (开发 Widget 时很有用)。
<debug>off</debug>
当 Widget 打开时，即使发生错误，也会保持关闭调试信息。此模式应只在为 Widget 彻底调试
时才可以使用。请注意，如果 Widget 产生了 10 个错误，无论此选项的设定是什么，调试主控台都
会显示出来。
<debug>verbose</debug>
当 Widget 打开时，会打开 Widget 调试信息，而且会使有关对象动作的信息以及其它自动触发
的事件显示出来 (开发 Widget 时很有用)。
 
注意事项
在 2.0.1 版或更高版本中，可以同时按住控制键 + shift 键并选择「装备」菜单，「调试模式」
选项将会出现。审核它将可使该选项打开后针对任何 Widget 启用调试。这表示，将不再需要在 Widget
中设定调试属性。
defaultTracking 设定图片的跟踪样式
说明
defaultTracking 属性可以指定图片的默认光标跟踪样式。它可以是 opacity (默认值) 或
rectangle，rectangle 可以让你在图片的矩形范围内的任何位置点击图片，而不是只能在图片的不透
明部分执行此动作。
 

范例
widget defaultTracking="rectangle">
...
</widget>
image 指定 Widget 的图标/图片
可以为 Widget 提供这个选用的信息。此属性中包含了要显示以代表 Widget 的 150x150 图片
的相对路径。目前，只有当第一次执行未知 Widget 时，或自从上一次执行后已被修改后，此图片才
会显示在我们的标准「安全」对话框中。未来，它也会在接口的其它标签中使用，因此你最好为 Widget
提供图片以及作者/公司/著作权信息。
 
可用性
适用于 3.0 版或更高版本。
minimumVersion 执行此 Widget 所需的 Widget Engine 的最低版本
说明
为 Widget 指定 minimumVersion 可以让 Widget Engine 针对正在执行的引擎的版本来检查它。
如果目前的版本低于指定的版本，将会为用户显示一条错误信息，而且 Widget 将不会执行。
 
范例
<widget minimumVersion="1.5">
...
</widget>
从 3.0 版及更高版本开始，此属性也通知了 Widget Engine 它可以启用新行为。我们会将这一
点当成提示，即 Widget 已经经过修改，可以与指定的最低版本搭配使用，就其本身而论，它也已经
经过调整，可以在该版本上产生正确的行为了。我们可以使用这个机制来使较旧 Widget 在未修改的
情况下继续执行，但在广告中强调支持 3.0 版的较新/已修改的 Widget 也可能需要修改，才能够在
新环境中执行。它基本上可以让我们改变项目的工作方式而无须中断现有 Widget。
option 各种 Widget 选项
说明
从整体上来讲，这些选项会影响 Widget 的行为。
<option>allowCustomObjectAttributes</option>
当指定了这个 Widget 属性后，将允许使用自订对象属性，而且不会触发调试的错误。对于会对
JavaScript 对象模型感到舒服的人而言，这将会是个进阶（高级？）的功能，但是它有个缺点，就是
对象属性名称 (例如 hOffset) 中如果出现简单的错字，将很难被找出来。
<option>dontRememberWindowPosition</option>
此选项可以通知 Widget Engine 当此 Widget 关闭时不存放它的窗口位置。一般情况下，所有
Widget 的位置都会在 Widget Engine 的多次叫用之间被记住，因此用户可以随意配置他们的桌面，
但是某些种类的 Widget 可以通过在每次执行时程序化地定位它们自己来更好地执行。

<option>allowArbitraryXML</option>
此选项可以关闭对于有效 XML 标签及属性名称的检查。如果要在 Widget 中内嵌未由 Widget
Engine 辨识的 XML，你应该指定此选项以避免发生错误 (请注意其它 XML 的格式必须正确)。此选项
基本上很少使用。
 
requiredPlatform 指定此 Widget 是否需要特殊平台才能执行
虽然 Widget 最好应在 Widget Engine 支持的所有平台上执行，但是 Widget 有时可能也会使用
高度特定的平台功能 (例如 Windows 上的 COM)。要指出 Widget 需要特殊平台，可以以数值
"macintosh" 或 "windows" 来指定此属性。
 
可用性
适用于 1.8 版或更高版本。
Version Widget 的版本号码
可以在此属性中指定 Widget 的目前版本。如果使用 <about-box> 对象中的 <about-version> 对
象，这就是显示出来的信息。
 
可用性
适用于 1.5 版或更高版本。
 
<window> 定义 Widget 的主窗口的标签
属性 (Attributes)
alignment
contextMenuItems
height
hOffset
level
name
onContextMenu
onFirstDisplay
onGainFocus
onLoseFocus
onMultiClick
opacity
shadow
title
visible
vOffset
width

 
说明
window 标签说明了 Widget 窗口的大小及位置。此窗口一定是透明的，而且只有你放到其中的图
片及文字才会显示给用户。
从 2.0 版开始， Widget 中就可以有多个窗口了。可以将窗口的变量指定为对象的窗口属性来将
对象 (图片、文字等) 附加到 窗口中。如此，每个对象都可以了解到它们的所在位置。
如果你为 窗口提供了一个名称 (在 XML 或在 JavaScript 结构式中)，Widget Engine 将会跟踪
窗口位置，并会为你自动将其存放为偏好设置。未命名的窗口的偏好设置将不会存放 (它们通常都是
一个小的暂时性窗口，例如 bezel，因此没有级数)。
每个窗口都可以保持它自己的窗口层级。但是，如果用户在「偏好设置」对话框中将 Widget 的
层级设定为一个数值，那么所有窗口都将会设定为该数值。如果你不要窗口采用此数值，请在
onPreferencesChanged 句柄中将其重设为要的数值。
alignment 窗口与的对齐方式
说明
它可以指定 Widget 窗口与其相关 hOffset 与 vOffset 的对齐方式。可能的数值包括：left、
right 或 center。以 left 方式对齐的窗口将会使其左上角位于指定的位移处；而以 right 方式对
齐的窗口则会使其右上角位于位移处；以 center 方式对齐的窗口将会使其正上方中心位于位移处。
默认窗口对齐方视为 center。
 
JavaScript
object.alignment
 
范例
<window title="My Widget">
<alignment>left</alignment>
</window>
myWindow.alignment = "left";
 
平台注意事项
目前，此属性在 Windows 上会遭到忽略。
 
contextMenuItems 指定菜单项目的数组。
说明
可以通过将 contextMenuItems 加到 窗口中，来将项目加到用户在 Widget 上点击鼠标右键时所
显示的标准菜单中。实际上，此标签对于 text、textArea 以及 image 对象都有效。也可以在
onContextMenu 标签上指定要执行的某些 JavaScript 来动态地建立 内容项目 (关于更进一步信息，
请参见 onContextMenu)。
可以包含 menuItem 对象的数组来指定 项目。关于它们的更进一步信息，请参见有关 menuItem 的
小节说明。
 
JavaScript
myObjectName.contextMenuItems

 
范例
<window>
...
<contextMenuItems>
<menuItem title="Test" onSelect="beep();"/>
<menuItem title="Another Test">
<onSelect>alert( 'hello' );</onSelect>
</menuItem>
</contextMenuItems>
...
</window>
请参见 onContextMenu 小节中有关在 JavaScript 中建立菜单的范例。
 
可用性
适用于 2.0 版或更高版本。
 
height 窗口的高度
说明
它可以指定 Widget 窗口的高度，单位为像素。
 
JavaScript
object.height
 
范例
<window title="My Widget">
<height>200</height>
</window>
myWindow.height = 250;
 
hOffset 窗口的初始水平位置
说明
window 标签的 hOffset 属性可以在 0,0 为屏幕左上角的基础上为窗口定义水平 (从左到右) 的
位移。指定的数值越大，窗口在屏幕中就显示得越远。
 
如果你未在 XML 中为 hOffset 指定数值，那么它就会在 Widget 的 onLoad 动作中显示为 –1
(负一)。 这可以让你程序化地确定初始窗口位置 (例如，无论屏幕分辨率为何都将其放置在右下角)。
 
JavaScript
object.hOffset
 

范例
<window title="My Widget">
<hOffset>200</hOffset>
</window>
myWindow.hOffset = 250;
 
level 窗口与其它窗口之间的关系
说明
此属性可以包含以下其中一个数值：konspose、desktop、below、normal、topmost 或 floating。
它可以指定窗口与桌面上其它窗口之间的关系，是显示在其它窗口下面还是浮动在所有窗口之上
(konspose 表示它只有在抬头显示器模式下才会显示)。默认值是 normal。
 
JavaScript
object.level
 
范例
<window title="My Widget">
<level>below</level>
</window>
myWindow.level = 'normal';
 
name 窗口的名称
说明
用来在 JavaScript 中识别窗口的名称。
 
JavaScript
object.name
 
范例
<window title="My Widget">
 <name>myWindow</name>
</window>
print(myWindow.name);
onContextMenu 显示菜单时调用
说明
要为 Widget 指定被加到标准菜单中的菜单项目，最简单的方法就是在 XML 中使用
contextMenuItems 标签。但是，对于那些需要动态建立其项目的 Widget 来说，onContextMenu 句柄
是你最好的工具。当即将要显示菜单时，在某些视图响应之前，它会按照视图顺序从前到后在鼠标底
下针对所有元素调用。处理此情况时，你只须建立菜单项目，并将 contextMenuItems 属性设定为项

目的数组即可。此窗口始终都可以让你新增项目，无论其前方的视图是否自己处理此信息皆是如此。
 
JavaScript
myWindow.onContextMenu
 
范例
<onContextMenu>
var items = new Array();
items[0] = new MenuItem();
items[0].title = "This is the title";
items[0].enabled = false;
items[0].checked = true;
items[0].onSelect = "alert( 'you chose it!' );";
items[1] = new MenuItem();
items[1].title = "This is the second title";
items[1].onSelect = "beep();";
myWindow.contextMenuItems = items;
</onContextMenu>
 
可用性
适用于 2.0 版或更高版本。
 
onFirstDisplay窗口第一次显示时调用
说明
只有在窗口第一次显示在 Widget 中时 (即我们看到没有针对位置存放的偏好设置时)，才会调用
窗口上的任何 onFirstDisplay 句柄。这可以让 Widget 决定当 Widget 第一次启动时应该显示的位
置。
 
范例
<onFirstDisplay>
setInitialPosition();
</onFirstDisplay>
请记住，只有当窗口第一次显示时，才会传送它。当针对该窗口存放了偏好设置之后，将绝对不
会再次接收此信息。
 
可用性
适用于 2.0 版或更高版本。
 
 
onGainFocus 窗口获得焦点时调用
说明

此句柄可让你在窗口快要启动时收到通知。可以利用这个时间来进行装饰等，以便在你希望的情
况下显示你已启动。在早于 2.0 的版本中，你只能在 Widget 层级执行此动作。在 2.0 版中出现了
多个窗口之后，你通常应该移动以使用窗口特定的句柄。
 
范例
<onGainFocus>
 showPlayButton();
</onGainFocus>
 
可用性
适用于 2.0 版或更高版本。
onLoseFocus处理窗口特定的停用。
说明
此句柄可让你在窗口快要停用时收到通知。可以利用此时间来移除可能已在启动时显示的任何装
饰等。在早于 2.0 的版本中，你只能在 Widget 层级执行此动作。在 2.0 版中出现了多个窗口之后，
你通常应该移动以使用窗口特定的句柄。
 
范例
<onLoseFocus>
 hidePlayButton();
</onLoseFocus>
可用性
适用于 2.0 版或更高版本。
 
onMultiClick多次按下鼠标按键是调用
说明
可以使用 onMultiClick 句柄轻松设陷按两下 (或按三下等)。此句柄可以在图片、文字与文字标
签对象上设定。无论何时调用 onMultiClick，都可以检查 system.event.clickCount 以查看数值为
何。它将永远是 2 (针对按两下) 或更大。
 
也可以在 onMouseUp 句柄中检查此 system.event.clickCount，以及替代使用 onMultiClick。
 
<onMultiClick>
if ( system.event.clickCount == 2 )
alert( "Double Click!" );
</onMultiClick>
 
可用性
适用于 2.0 版或更高版本。
 

opacity窗口的透明度
说明
可以影响整个窗口及其内容的透明度的 0 到 255 之间的数值。
 
JavaScript
object.opacity
 
范例
 
<window title="My Widget">
<opacity>180</opacity>
</window>
myWindow.opacity = 255;
 
shadow 设定阴影的属性
说明
控制 Widget 是否有阴影。
 
注意：对于 Mac OS X 10.2 来说，当你打开此功能时，在窗口周围还会有一圈灰色的边界。当设
计 Widget 时，请牢记这一点。目前，此边界不会显示在 Windows 上。
 
JavaScript
object.shadow
 
范例
<window title="My Widget">
<shadow>false</shadow>
</window>
myWindow.shadow = true;
 
Windows 平台注意事项
窗口阴影适用于 3.1 版或更高版本。必须针对函数的此属性将 Widget 的最低版本需求设定为
3.1。
title窗口标题
说明
在菜单中，它目前做为 Widget 的名称来使用。
 
JavaScript
object.title
 

范例
 
<window>
<title>My Widget</title>
</window>
myWindow.title = "My New Widget";
 
 
visible控制窗口可见与否
说明
适用于在窗口的 XML 定义中将其设定为 false，然后在已结构 Widget 之后在 onLoad 触发器的
结尾将其设定为 true 来隐藏动态 Widget 的初始建立。
请注意，如果 visible 属性为 false， Widget 将不会显示在屏幕上，而且将无法与其互动。
 
JavaScript
object.visible
 
范例
<window title="My Widget">
<visible>false</visible>
</window>
myWindow.visible = true;
 
vOffset窗口的初始垂直位置
说明
window 标签的 vOffset 属性可以在 0,0 为屏幕左上角的基础上为窗口定义垂直 (从上到下) 的
位移。指定的数值越大，窗口就会显示得越往下。
如果你未在 XML 中为 vOffset 指定数值，那么它就会在 Widget 的 onLoad 动作中显示为 –1
(负一)。 这可以让你程序化地确定初始窗口位置 (例如，无论屏幕分辨率为何都将其放置在右下角)。
 
JavaScript
object.vOffset
 
范例
<window title="My Widget">
<vOffset>200</vOffset>
</window>

width窗口的宽度
说明
它可以指定 Widget 窗口的宽度，单位为像素。
 
JavaScript
object.width
 
范例
<window title="My Widget">
<width>200</width>
</window>
 
 
JavaScript 参考
本节将会为你介绍 Widget Engine 所提供的 JavaScript 扩展。如果你是第一次使用
JavaScript，请先取得此语言的指南，以帮助你了解其语法与结构。Yahoo! Widget Engine 内建了
JavaScript 引擎 (Mozilla Spidermonkey)，符合 JavaScript 1.5 标准 (ECMA262，
修订版本 3)。
. 通用函数
 
. 系统函数
 
. 系统属性
 
. 系统对象
 
. Widget Engine 对象方法
 
 
通用函数 (Global Function)
这些函数可以在 JavaScript 中的任何地方使用。
 
alert() 显示警告对话框
语法定义
 
alert(string, [button one, button two, button three])
 
属性 (Attributes)

string
将会显示的警告文字内容。
button one
显示在警告上的第一个 (或唯一) 按钮上的文字。
 
此自变量为选用。
button two
显示在警告的第二个按钮上的文字。此自变量为选用。
 
 
button three
显示在警告的第三个按钮上的文字。此自变量为选用。
 
 
 
返回
将警告对话框显示给用户之后，对话框会根据按下的按钮返回 1、2 或 3。
说明
可以用来在标准的警告对话框中为用户提供实时信息，或要求他们从最多三个选项中挑选。返回
数值可以是 1、2 或 3，以指出按下的是这三个选用按钮之中的哪一个。
范例
alert("The time is now " + Date());
answer = alert("Do you wish to continue?", "Yes", "No");
if (answer == 2)
closeWidget();
 
 
appleScript() 执行 AppleScript
语法定义
appleScript(appleScriptCode[, timeout])
 
参数
 
appleScriptCode
包含要执行的完整 AppleScript 程序代码片段的字符串。如果此字符串只由一个有效文件名称组
成，那么程序代码将会从该文件中加载。
 
timeout
等待 AppleScript 完成的选用秒数。出于兼容性的考虑，默认逾时为 2 秒。
 
说明
使用此函数， Widget 可以通过 AppleScript 调用控制「系统」的元素或应用程序。
AppleScript 必须格式化为非断行程序行，使用新行字符来表示实际中断。我们建议你，在 Widget
中使用 AppleScript 之前，先在 Apple 的 Script Editor 应用程序中预先格式化并验证
AppleScript。
iTunes Remote Widget 可以让你广泛使用 appleScript() 调用。
 
范例

 
// 注意在 AppleScripts 中所需要的
// 内嵌新行。
appleScript('tell application "Internet Explorer"/nOpenURL ("' +
newURL + '")/nend tell/n');
 
beep() 播放警告音
语法定义
beep()
说明
此函数可以让用户的 Mac 发出哔声。如果需要提醒用户注意、要通知他们工作已完成，或为
Widget 代码调试，这个函数是很有用的。
范例
if (done)
beep();
bytesToUIString() 将字节数组转换为容易使用的字符串
语法定义
 
string = bytesToUIString(integer)
 
说明
 
在大多情况下，最好将特定的字节数转换为如 "1K" 或 "34.2M" 这样的字符串。此函数正好可以
满足 需求。
 
范例
 
print( "There is " + bytesToUIString( numBytes ) + " memory
available" );
 
可用性
 
适用于 2.0 版或更高版本。
 
chooseColor()
建立标准的色彩选择对话框，让用户选择颜色
 
语法定义
 

string = chooseColor( [string] );
 
说明
 
可以使用此函数来显示平台的标准色彩选择器，并让用户选择颜色。此外，也可以选择传送选择
为参数的初始颜色。此函数会将颜色返回为 16 进位的字符串 (例如 "#FF0000")，如果用户取消此对
话框，则会返回 null。
 
范例
 
print( chooseColor( "#EEEEEE" ) );
 
可用性
 
适用于 2.0 版或更高版本。
 
ChooseFile() 建立标准文件对话框，且允许用户选择文件
语法定义
file = chooseFile([string | array]);
说明
可以使用此功能来显示平台的标准打开对话框，并允许用户选择文件。也可以选择将单一延伸或
延伸的数组传送至此功能中，以限制用户可以选择的文件类型。如果用户取消了对话框，则将会返回
空值。
 
范例
 
print( chooseFile() ); // 选择任何文件
print( chooseFile( ".png" ) ); // 仅 PNG 文件
print( chooseFile( new Array( ".png", ".jpg" ) ) )
 
可用性
 
适用于 2.0 版或更高版本。
 
 
chooseFolder() 建立标准文件对话框，且允许用户选择文件夹
语法定义
 
file = chooseFolder();
 
说明
 

可以使用此功能来显示平台的标准打开对话框，并允许用户选择文件夹。如果用户取消了对话框，
则将会返回空值。
 
范例
 
print( chooseFolder() );
 
可用性
 
适用于 2.0 版或更高版本。
 
convertPathToHFS()将 UNIX 样式路径转换为 HFS 样式路径
语法定义
convertPathToHFS(myPath[, localize])
 
说明
将 UNIX 样式路径 (含 '/') 转换为 Mac HFS 样式路径 (含磁盘区名称与 ':')。如果选用的第
二个布尔参数为 true，则返回的路径将会本地化为目前的系统语言。请注意，如果要求本地化的路径，
必须存在路径所应用的文件，转换才能成功。
 
范例
 
convertPathToHFS('/Users/joe/foo.txt');
 
产生：
 
Macintosh HD:Users:joe:foo.txt
 
在德文系统上：
 
convertPathToHFS('~/Movies', true)
 
产生：
 
Macintosh HD:Benutzer:joe:Filme
 
Windows 注意事项
 
此功能将会在 Windows 上返回空白字符串。
 
convertPathToPlatform() 将 JavaScript 样式路径转换为平台特定样式路径
语法定义

 
convertPathToPlatform(myPath[, forDisplay])
 
说明
 
将 JavaScript 样式文件路径 ("/foo/bar/baz") 转换为平台样式路径 (例如在 Windows 上，
"//foo//bar//baz")。请注意，依照默认，路径将会逸出 (含任何双倒斜线)，可随时供 runCommand()
使用。如果要适合显示给用户的路径，请为选用的第二个参数指定 true。
此功能无法在 Macintosh 上使用 (路径已是正确格式)。
范例
 
convertPathToPlatform('c:/temp/foo.txt');
 
在 Windows 上产生：
 
c://temp//foo.txt
 
与
 
convertPathToPlatform('c:/temp/foo.txt', true);
 
在 Windows 上产生：
 
c:/temp/foo.txt
 
 
closeWidget() 关闭 Widget
语法定义
 
closeWidget()
 
说明
 
就像用户已从菜单中选取了关闭 Widget 一样关闭目前正在执行的 Widget。
 
范例
answer = alert("Do you wish to continue?", "Yes", "No");
 
if (answer == 2)
closeWidget();
 
 

escape() 编码字符串以做为安全的 URL 使用
语法定义
 
escape(string)
 
属性 (Attributes)
 
String 主要目的为做为 URL 使用的包含文字的字符串。
返回
包含自变量的字符串，但其含有不适合转换为其逸出对应者的 URL 的字符。
说明
如果你要从用户偏好设置中搜集要通过 URL 传送的信息，这个功能将十分有用。它可以在将字符
串传送至 URL 句柄之前省去你亲自验证字符串的步骤。
范例
// 单引号、空格与 & 将会
// 由 URL 逸出字符取代
mySearch = "Konfabulator's FAQ & JavaScript Reference";
openURL("google.com/search?q=" + escape(mySearch);
参见
unescape()
 
 
focusWidget() 将 Widget 移至前景
语法定义
 
focusWidget()
 
说明
 
将 Widget 移至用户桌面上的前景。当响应热键时，此功能十分有用。
 
请注意，如果 Widget 于未要求时移至前景，则将会惹烦用户而可能将 Widget 丢到回收站中。
 
范例
<hotkey name="hkey1">
<key>F2</key>
 <modifier>command+control</modifier>
<onKeyUp>focusWidget();</onKeyUp>
</hotkey>
 
 

form() 按照用户要求产生窗体
 
语法定义
form(fieldArray, [dialogTitle], [confirmButtonLabel],
[cancelButtonLabel])
 
说明
 
form() 最多含四个自变量，第一个是 FormField 对象的「数组」(其拥有与在 XML 中定义的偏
好设置对象相同的自变量)。窗体字段的数组可用来定义显示给用户的对话框。当用户按下「确认」按
钮时，form() 功能将会返回代表在窗体中所输入数值的字符串数组 (如果按下「解除」按钮，则将会
返回空值)。剩余的自变量依序为对话框的标题、「确认」按钮的标签以及「解除」按钮的标签。最后 3
个自变量为选用。
 
范例
 
var formfields = Array();
 
formfields[0] = new FormField();
formfields[0].name = 'name1';
formfields[0].type ='text';
formfields[0].title = 'Text Pref Title';
formfields[0].defaultValue = 20;
formfields[0].description = 'This is a description of a text field.';
formfields[1] = new FormField();
formfields[1].title = 'Basic Field';
formfields[3] = new FormField();
formfields[3].name = 'name4';
formfields[3].title = Checkbox Pref Title';
formfields[3].type = 'checkbox';
formfields[3].defaultValue = 1;
formfields[3].description = 'This is a description of a checkbox field.';
formResults = form(formfields, 'my title', 'Save It And Continue');
 
if (formResults != null) {
print("formResults = " + formResults);
} else {
print("form was cancelled");
}
 
include() 包括其它 JavaScript 文件的内容
语法定义
 

include(string)
说明
 
包括代码中目前位置上已指定文件的内容。这将以内部等于较旧样式方法的方式完成：
 
eval(runCommand("cat onload.js"));
 
唯一不同的是 include() 会安排让任何错误信息拥有正确的文件名称与行号。
 
范例
 
include("onload.js");
 
isApplicationRunning() 如果正在执行指定的应用程序，返回 true
语法定义
isApplicationRunning(string)
 
说明
可以使用此函数来判断目前是否正在执行应用程序。在你于 Windows 上执行例如叫用 Mac 或 COM
上 AppleScript 的操作之前，此函数将会很有用。传送你感兴趣的应用程序名称，而非完整路径。
 
范例
// 在 Mac 上
if ( isApplicationRunning( "iTunes" ) )
 
// 在 Windows 上
if ( isApplicationRunning( "itunes.exe" ) )
 
平台注意事项
 
请注意，这是必须使用平台的精确名称的标签。如上所示，在 Windows 上，针对应用程序名称参
数，可以使用 "itunes.exe"，反之在 Macintosh 上，你只能使用 "itunes"。
 
可用性
 
适用于 2.0 版或更高版本。
 
konfabulatorVersion() 将 Widget Engine 的目前版本做为字符串返回
语法定义
 
konfabulatorVersion()
 

说明
 
可以针对信息的目的使用此函数，或者也可以控制不同版本 Widget Engine 上的程序代码行为。
 
范例
 
print( "This version is " + konfabulatorVersion() );
 
 
 
log()
在调试窗口中显示含时间戳记的字符串
 
语法定义
 
log(string)
 
说明
 
常用于调试。请注意，将需要在 Widget 的 XML 中指定：
 
<debug>on</debug>
 
才能看到输出结果。
 
范例
 
log("idx = " + idx);
 
 
 
openURL() 在默认网页浏览器中打开指定的 URL
语法定义
openURL(validURL)
 
说明
 
使用此函数来启动 URL 将会使 URL 以在用户的「因特网系统偏好设置」中设定的适当应用程序
来启动。如果自变量为正确格式的 URL，此函数将会返回 true，否则将会返回 false。请注意，即使
是正确格式的 URL 也可能指向不存在的资源，因此 Widget Engine 可能会返回真，而 浏览器仍会提
出抱怨。
范例
openURL("http://widgets.yahoo.com");
openURL("ftp://myname:[e-mail]");

参见
 
escape(), unescape(), URL.fetch()
 
play( ) 播放音效文件
语法定义
 
play(pathToSound[, truncate])
 
说明
支持的格式有 MP3、AIFF、AU、WAV 与 SND。调用将会立即返回且会异步播放声音。pathToSound
必须指向用户硬盘机上某处或 Widget 包中的有效音效文件。选用的第二个布尔参数将会指定新的声
音是否应该截断 (停止) 任何目前正在播放的声音。
 
范例
 
play("sounds/sample.mp3");
play("sounds/bark.aiff", true);
 
popupMenu() 在指定位置显示popup菜单
语法定义
popupMenu( menuItems, x, y );
说明
此函数可以让你在指定的位置显示popup菜单。可以在第一个参数中传送 menuItem 对象的数组，
这跟在菜单中很像。x 与 y 坐标皆会在窗口坐标中传送。
只应在处理鼠标往下事件时调用此函数。
 
范例
 
// 在鼠标的位置显示快捷菜单
<onMouseDown>
 var items = new Array;
 items[0] = new MenuItem;
 items[0].title = "This is item 1";
 items[0].enabled = true;
 items[1] = new MenuItem;
 items[1].title = "this is item 2";
 items[1].enabled = true;
popupMenu( items, system.event.hOffset,
system.event.vOffset );
</onMouseDown>
 

可用性
 
适用于 2.1 版或更高版本。
 
 
print()在调试窗口中打印字符串
语法定义
 
print(string)
 
说明
 
常用于调试。请注意，将需要在 Widget 的 XML 中指定：
 
<debug>on</debug>
 
才能看到输出结果。
 
范例
 
print("idx = " + idx);
 
prompt() 在特定条件下提示用户
语法定义
prompt(<promptText>, [defaultValue], [dialogTitle], [confirmButtonLabel],
[cancelButtonLabel])
promptText
显示给用户的提示。
 
defaultValue
产生文字字段的数值 (以及当用户没有改变任何内容时将会返回的数值)。
 
dialogTitle
将会用于对话框的标题。
 
confirmButtonLabel
确认用户对对话框所进行的改变的按钮标签。
 
cancelButtonLabel
用于取消对话框的按钮的标签。
 
说明

 
用来从用户处取回文字字符串。这是在 form() 中找到的功能子集，其提供的目的是为了易于编
写程序。请注意，如果用户取消了此对话框，则将会返回 null。
 
范例
result = prompt("Name:", "Your Name","Name Dialog", "OK", "Cancel");
 
if (!result)
result = "no name";
 
random() 返回随机数字
语法定义
 
random([lower_limit, upper_limit])
 
说明
 
在指定的限制中选择性地产生随机数字。请注意，返回的数值中可能包括下限，但绝对不会有上
限。
 
范例
// 这将会返回介于 0 与 64K 之间的随机数字
number = random();
// 这将会返回介于 0 与 100 之间的随机数字
percentage = random(100);
// 这将会返回介于 27 与 72 之间的随机数字
number = random(27,72);
reloadWidget()
使 Widget 重新加载它自己
 
语法定义
 
reloadWidget()
说明
 
有时候最好让 Widget 重新启动。调用此函数将会产生如同用户已于在装备菜单中选择 Widget 时
按住命令一样的结果。
 
参见
closeWidget(), focusWidget()
 
 

 
resolvePath() 解析系统文件路径
语法定义
resolvePath(pathToFile)
 
说明
 
此函数可以在所提供的路径中进行以下改变：
. 将初始波状符号表达式 (例如 ~/Pictures) 扩展至正确的目录 (例如 / Users/joe)
 
. 将目前目录中的空白组件与应用 (亦即顺序 "//" 与 "/./") 减少为单一路径分隔符。
 
. 如果可能，请只在绝对路径中将对于父目录 (亦即组件 "..") 的应用解析至真实父目录，这
会咨询文件系统来解析每个可能的符号连结。
 
. 因为无法在相对路径中解析符号连结，因此父目录的应用将不会移动。
. 如果结果仍然指示现有文件或目录 (已通过咨询文件系统来检查)，则将可从路径中移除
/private 的初始组件。
 
. 如果路径是 HFS+ 别名，则将会返回别名目标的文件名称 (请注意，这将只适用于最
终路径元素，路径中内嵌的别名将无法解析，如果需要，则可能必须特别处理)。
 
. 如果指定的路径是 "."，它会扩展至目前目录的完整路径。
范例
 
realPath = resolvePath(myPath);
 
resumeUpdates() 允许 Widgets 动态视觉更新
语法定义
resumeUpdates()
说明
 
JavaScript 程序代码可影响 Widget 窗口中所有对象的配置。如果 Widget 较复杂，要个别地显
示这些改变内容可能会很不容易 (也可能会不太有吸引力)。以 suppressUpdates() 与
resumeUpdates() 括住重新排列 Widget 可见部分的程序代码标签，Widget 作者将可控制用户所看见
的内容。
参见
 
suppressUpdates(), updateNow()
 

runCommand() 执行壳层命令并返回结果
语法定义
 
runCommand(string)
说明
此函数可以执行操作系统的 UNIX 层中的任何命令执行，并将结果存放在字符串变量中。请注意，
只有用户拥有权限的命令才可以执行。
如果结果的最后一个字符是新行，它将会遭到移除。
范例
str = runCommand("ls -l /");
print(str);
runCommandInBg()
在背景中执行壳层命令
 
语法定义
 
runCommandInBg(string, tag)
说明
此函数会取用 UNIX 命令与 tag，并在后台中执行命令 (亦即不会等待它完成)，当它完成之后，
会使称为 onRunCommandInBgComplete 的全局动作触发，并将名为 tag 的变量数值设定为命令的结果
(system.event.data 的数值会设定为 tag 的名称)。命令结束的的顺序可能与其开始的顺序无关。
请注意，当后台命令结束时，system.event.data 的数值将会改变，并且如果你一次在后台中执
行多个命令，则此情况也可在动作中发生。你应该在 onRunCommandInBgComplete 动作开始时存放数
值，以避免得到意外的结果。另外请注意，tag 可指定将会接收数据的变量的名称，而非变量本身。
 
范例
<action trigger="onLoad">
 var yahooData;
runCommandInBg("curl www.yahoo.com", "yahooData");
</action>
<action trigger="onRunCommandInBgComplete">
print("onRunCommandInBgComplete for tag: " + system.event.data);
print("Yahoo's home page is " + yahooData.length + " bytes");
</action>
 
 
 
saveAs() 显示标准 SaveAs 对话框
语法定义
string = saveAs([string | array])

 
说明
 
有时候，你可能会要询问用户要将文件存放于何处。此函数可以让你显示标准对话框，以允许用
户选择目的文件夹。文件夹的路径将会返回。如果用户取消了对话框，则将会返回空值。
此函数会将选用的字符串或字符串数组做为参数。此参数会设定可以存放的可能的后缀名，与
chooseFile() 类似。
 
范例
destination = saveAs();
if ( destination != null )
 saveFileTo( destination );
destination = saveAs( new Array( ".png", ".jpg" ) );
if ( destination != null )saveFileTo( destination );
 
可用性
 
适用于 2.0 版或更高版本。
 
savePreferences() 存放 Widget 的偏好设置
语法定义
 
savePreferences()
 
说明
 
通常，当用户使用「Widget 偏好设置」面板进行编辑或当 Widget 结束时，Widget 的偏好设置
都将会自动存放。如果 Widget 正在 JavaScript 中操纵偏好设置数值，便可确定其可通过调用此函
数的及时方式存放到磁盘中。
 
showWidgetPreferences() 打开 Widget 的偏好设置面板
语法定义
showWidgetPreferences()
说明
当用户从菜单中选取了 Widget 偏好设置之后，此函数将会打开「Widget 偏好设置」面板。它常
用来提供 Widget 操作面板上的偏好设置按钮，或于 Widget 第一次执行时取得初始偏好设置。
 
sleep() 暂停代码执行进入休眠状态
语法定义

sleep(number)
 
说明
 
暂停执行 Widget 的程序代码指定的毫秒数 (一千分之一秒)。
 
范例
// 暂停代码一秒钟
sleep(1000);
 
speak() 读出文字
语法定义
speak(string)
 
语法定义
speak(theText)
 
说明
 
此函数可以计算机默认语音读出指定的文字 (其可使用「系统偏好设置」中的「语音」面板来设
定)。
 
范例
speak("Now there's something you don't see everyday.");
speak("Unless you're me.");
 
 
 
suppressUpdates() 使 Widget 等待视觉更新
语法定义
suppressUpdates()
 
说明
 
阻止屏幕更新，直到出现 resumeUpdates() 调用为止。或者，也可以使用 updateNow() 手动执
行更新。阻止更新可以提高性能或为 Widget 用户隐藏混乱的过渡状态。
 
参见
resumeUpdates(), updateNow()
 

tellWidget() 将信息传送给另一个 Widget。
语法定义
 
tellWidget(nameOrPath, message);
 
说明
 
可以使用 tellWidget 来在 Widget 之间传送信息。为了使传送成功，接收方的 Widget 必须拥
有 onTellWidget 句柄。信息将会在 system.event.data 中传送。Widget 作者可以自主决定是否接
受信息内容。在最简单的形式下，可以传送 Javascript 并 eval() 它，这并不是十分安全的，因为
你不知道这些JavaScript 可能会做什么。因此，Widget 作者需要考虑与此相同由消息机制支持的一
些特殊情况。例如，网络摄影机可能支持「重新加载」做为其支持的动作。
 
<action trigger="onTellWidget">
if ( system.event.data == "reload" )
reloadCamPicture();
</action>
 
在我们的「PIM 总览 Widget」中，我们已经确定了以下结构：
 
msg = action ":" params
params = (param) (";" param)*
param = name "=" value
"action"、"name" 与 "value" 只是字符串。也许数值也可以加上引号。
可以将信息传送至 Widget 的名称 (只要它正在执行或存在于用户的 Widgets 文件夹中)，或
Widget 的路径中。另外，目前这是一个单向信息。稍候的版本将会允许将响应传送回来。
这是在 Mac 上的 AppleScript 与 Windows 上的 COM 中内建的。这表示可以在 Mac 上的
AppleScript 中撰写代码，或在 Windows 上使用 Jscript 或 VB 等来将信息传送给 Widget。
 
可用性
 
适用于 2.0 版或更高版本。
 
平台注意事项
 
目前，如果 Windows 能够找到 Widget，Windows 就会启动它。如果 Widget 没有执行而你提供
了完整的路径，Mac 将只会启动 Widget。将来，将会由布尔参数来更精确地控制此操作。
 
安全注意事项
 
应该反复检查输入信息，且绝对不要只 eval() 信息。
 

unescape() 译码包含 URL 逸出的字符串
语法定义
unescape(string)
 
说明
 
这是 escape() 的反义函数。
 
范例
encURL = escape(url);
 
url = unescape(encURL);
 
updateNow() 强制进行 Widget 的视觉更新
语法定义
 
updateNow()
 
说明
 
通过在需要时使用 suppressUpdates() 以及调用 updateNow()，Widget 作者可以完全控制其
Widget 的显示方式。请注意，如果程序代码无法在阻止更新时调用 updateNow()，则屏幕可能不会反
映出 Widget 的真实状态。
 
范例
updateNow();
参见
 
resumeUpdates(), suppressUpdates()
 
 
yahooCheckLogin() 检查是否已登陆
语法定义
 
boolean yahooCheckLogin()
 
说明
 
此函数可用来查看目前用户是否已登陆其 Yahoo! 账号。如果函数返回 true，表示他们已登陆，
如果函数返回 false，则可明显推测出：他们没有登陆。可以使用此函数来判定你是否可成功使用需

要已登陆用户的 Yahoo! API。
 
范例
 
var loggedIn = yahooCheckLogin();
 
参见
 
yahooLogin(), yahooLogout()
 
可用性
 
适用于 3.0 版或更高版本。
 
 
yahooLogin() 进行登录
语法定义
boolean yahooLogin()
 
说明
 
如果使用需要用户登陆的 Web API，此函数可用来登陆用户的 Yahoo! 账号。如果
yahooCheckLogin() 返回 false，你便可调用此函数。它将会显示出标准的 Yahoo! Widget Engine 登
陆对话框，以提示用户输入他们的用户名称与密码。
此调用通常可以异步运作。如果用户已经登陆，yahooLogin() 将会简单返回 true，这时候就完
成了。如果 yahooLogin() 返回 false，则用户需要验证。此动作将会于 Widget 有空做其它事情的
时候自动发生。当用户最终验证时，将会经由 onYahooLoginChanged 动作收到通知。可以在此处调用
yahooCheckLogin() 以查看现在用户是否已经登陆。
一般而言，当 Widget 于使用需要已登陆用户的 API 来尝试做任何事情之前启动时，即使你还
没有登陆，你也应该等待 onYahooLoginChanged 事件。
范例
var loggedIn = yahooCheckLogin();
if ( !loggedIn )
yahooLogin();
// 于用户验证时执行我们业务。
// 在 XML 中：
<action trigger="onYahooLoginChanged">
if ( yahooCheckLogin() )
RefreshInformation();
else
LoggedOut();
</action>

请注意，在我们的 onYahooLoginChanged 动作中，我们也必须处理我们已经注销的情况。当发生
这种情况时，你可能需要清除 显示内容，然后为用户提供一个再次登陆的方法。你可能会在未预期的
时间注销，因此必须准备好处理这种情况。
可用性
适用于 3.0 版或更高版本。
 
参见
yahooCheckLogin(), yahooLogout()
 
可用性
 
适用于 3.0 版或更高版本。
 
yahooLogout() 注销用户的 Yahoo! 账号
语法定义
yahooLogout()
说明
此函数要求 Widget Engine 注销用户的 Yahoo! 账号。此函数将会于搁置要求时立即返回。完成
时，所有的 Widget 都将会收到 onYahooLoginChanged 动作，且 yahooCheckLogin 将会返回 false。
Widget 必须准备处理用户已经注销的情况。如果以前的有效证书已经过时，则可能会发生这种情况，
因此请随时准备好处理注销的情况。另外请记住，此调用将会影响所有需要用户的 Yahoo! 证书才能
使用 Yahoo! API 的 Widget。它并不只会影响到目前的 Widget。
范例
yahooLogout();
// 于发生注销时执行我们的业务。
// 在 XML 中：
<action trigger="onYahooLoginChanged">
if ( yahooCheckLogin() )
RefreshInformation();
else
LoggedOut();
</action>
可用性
 
适用于 3.0 版或更高版本。
 
参见
 
yahooCheckLogin(), yahooLogout()
 
可用性
 
适用于 3.0 版或更高版本。
 

 
System 属性与函数
这将会为 JavaScript 程序代码提供存取不同系统设定值与硬件信息的能力。
 
COM 在 Windows 上调用 COM 接口的函数
createObject
connectObject
disconnectObject
 
说明
COM 对象是让 Widgets 调用系统中 COM 接口的一种方法。例如，可以使用它来与 iTunes (如果
你没有使用我们的内置支持)、MSN Messenger、Outlook 上的朋友交谈。
 
COM.createObject( progID|CLSID ) 可连接任何 COM 对象
COM 接口需要提供足够的类型信息。目前无法支持对于方法的懒惰绑定法，所有类型信息都需要
在最前面提供 (亦即，ITypeInfo 接口需要返回适当的信息，如此我们便可执行自我检查以取得诸如
参数及其类型等项目的信息)。
 
范例
 
var it = COM.createObject( "iTunes.Application" );
track = it.CurrentTrack;
print( track.Album );
print( track.Artist );
以下是可从 MSN Messenger 中输出一些信息的另一个范例：
 
messenger = COM.createObject( "Messenger.UIAutomation" );
contacts = messenger.MyContacts;
num = contacts.Count;
for ( i = 0; i < num; i++ ) {
contact = contacts.Item( i );
print( " " + contact.FriendlyName + " " + contact.Status );
}
 
此程序代码只有在登陆 MSN Messenger 之后才有用。像联络人「状态」之类的项目可以通过网页、
MSDN 等找到。
它也可以连接「事件接收」(event sink)。相对于轮询，此函数将允许你让应用程序于事件改变 (如
好友状态等) 时通知你。COM.connectObject 将会告知 Widget Engine 收到对象事件的通知。

 
COM.connectObject
连接对象以获取对象事件
 
语法定义
COM.connectObject(object,prefix)
说明
此函数可以让你连接至对象以获取事件。在 COM 的世界中，许多对象都拥有可以让你获取事件的
事件接口。例如，可以连接 iTunes 应用程序对象，它会告诉你播放机何时开始与停止，以及应用程
序即将结束的时间。
你传入的对象必须已通过 COM.createObject 建立，或已通过调用COM 对象取得 (例如，如果你
从 iTunes 接收了一个曲目，而它拥有事件接口的话，你便可以使用该 iTunes 曲目)。
对于第二个参数，可于事件发生时传送将被调用的函数前缀。例如，当播放机开始播放曲目时，
iTunes COM 界面将会送出 "OnPlayerPlayEvent" 来将已开始播放的曲目传送给它。前缀可以帮助我
们寻找要调用的函数。当事件发生时，它将会尝试调用名为 <prefix>OnPlayerPlayEvent() 的函数。
以下是获取该事件的范例。
 
范例
 
var iTunesObj = COM.createObject( "iTunes.Application" );
COM.connectObject( iTunesObj, "iTunes_" );
function iTunes_OnPlayerPlayEvent( track )
{
print( "Started to play " + track.Name );
}
 
请注意，我们的函数叫做 iTunes_OnPlayerPlayEvent，它是我们指定的前缀组合，并且是可受到
叫用的 COM 方法的名称。另请注意，我们也接收到了代表曲目的另一个 COM 对象的参数。我们可以
从此处应用其 Name 属性。
 
当你完成对象操作并准备聆听其事件时，你应该小心调用 disconnectObject。
 
每个对象一次只能有一个已建立的事件接收。
 
注意事项
 
如果此函数无法成功连接，将会发生异常状况。建议你在 try/catch 句柄中调用此函数。
 
可用性
 
适用于 2.0 版或更高版本。
 

COM.createObject
通过 ProgID 或 CLSID 建立 COM 对象
 
语法定义
 
COM.createObject( progID | CLSID )
 
说明
 
这是在 COM 这个迷雾森林中顺利开出一条大道的起点。这里的秘诀是要找出可以调用的接口。遗
憾的是，缺少对于 COM 浏览器的认识以及使用尝试错误的方法，并没有更简单的方法能够达到这个目
的。某些信息可以通过网页取得 (如果你要搜寻例如 "automation" "COM" 及你最喜爱的应用程序等
项目，执行快速 Yahoo 搜寻将可产生你要的结果)。也可以使用 regedit 来寻找 ProgID。但是实际
上，Visual Studio 所提供的 COM 浏览器可能是最佳的方法 (如果你已经拥有 Visual Studio，它也
将是最经济的方法)。
 
范例
var iTunesObj = COM.createObject( "iTunes.Application" );
可用性
 
适用于 2.0 版或更高版本。
 
COM.disconnectObject
中断之前使用 connectObject 建立的事件接收
语法定义
COM.disconnectObject( object )
说明
在你完成使用对于 connectObject 的调用来建立事件接收之后，你应该调用此函数来中断联机。
由于某些应用程序的编写方法不同，在某些情况下，于释放主要 COM 对象之前执行此函数是很重要的。
范例
COM.disconnectObject( iTunesObj );
可用性
适用于 2.0 版或更高版本。
 
filesystem
取得文件系统中的信息及与文件系统互动
 
语法定义
 
filesystem
说明

 
filesystem 对象可提供 Widget 将在其上执行的对于系统基础文件及目录的存取。关于个别函数
与属性的详细信息，请参见以下内容。
请注意，在 3.1 版及更高版本中，Windows 引擎将不允许 filesystem 对象改变 C:/Windows (或
者设定为任何名称的 Windows 目录) 中的任何内容。由于文件权限的关系，Mac 版本将免费取得此行
为。
 
属性 (Attributes)
volumes
 
函数
copy()
emptyRecycleBin()/emptyTrash()
getDirectoryContents()
getDisplayName()
getFileInfo()
getRecycleBinInfo()/getTrashInfo()
isDirectory()
itemExists()
move()
moveToRecycleBin()/moveToTrash()
open()
openRecycleBin()/openTrash()
readFile()
reveal()
writeFile()
可用性
filesystem 对象适用于 1.8 版或更高版本。
 
 
filesystem.copy()
将文件复制到位置上
 
语法定义
 
filesystem.copy( path, destination );
 
说明
此函数可以让将文件复制到指定的目的地。来源可以是单一路径，或路径的数组。
如果只复制一个文件，则不需要存在目的地。在这种情况下，假设的目的地便是文件的新文件名
称。如果目的地存在，则假设它将会指定可在其中复制新文件的目录。
如果复制多个文件，目的地必须是存在的目录。
如果成功，此函数将会返回 true，否则将会返回 false。
 

范例
// 将文件复制到文件夹中
filesystem.copy( "myfile.txt", "/Users/evoas" );
// 复制文件
filesystem.copy( "myfile.txt", "myfile_copy.txt" );
 
可用性
 
适用于 2.0 版或更高版本。
 
 
 
filesystem.emptyRecycleBin() filesystem.emptyTrash() 清空系统回收站
 
语法定义
filesystem.emptyRecycleBin() filesystem.emptyTrash()
 
说明
 
此函数仅清空回收站/资源回收筒。如果用户已设定为查看警告对话框等，它将会自动出现。
此函数有两个名称，以反应出在两个平台 (Windows 与 Mac OS X) 上所使用的不同用语。
 
范例
fileystem.emptyTrash();
 
可用性
适用于 2.0 版或更高版本。
 
filesystem.getDirectoryContents() 取得目录中文件的名称
语法定义
array = filesystem.getDirectoryContents(directory, recurse)
 
说明
以选择性递归 (降序) 的方式将指定目录中的文件名称获取至每个子目录中。
 
范例
fileList = filesystem.getDirectoryContents(path, false);
 
注意事项
对于 2.0 版而言，目前此函数在 Mac 与 Windows 上的行为都是相同的。现在它一定会返回你传
送的位于根目录中的名称数组，而绝不会是完整路径。之前，如果你传入了一个完整路径，Windows 也
将会返回完整路径。

 
可用性
适用于 1.8 版或更高版本。
 
 
filesystem.getDisplayName() 返回文件的好记名称
语法定义
filesystem.getDisplayName( path )
说明
此函数将会返回文件路径的显示名称。显示名称基本上就是你在 Finder 或 Explorer 中看见的
内容。例如，如果文件的后缀名应该要隐藏，此函数将会移除它。基本上可以获得保证输出你在 OS 中
所看见的文件路径的相同名称。
范例
print( filesystem.getDisplayName( "C:/" ) );
 
可用性
适用于 2.0 版或更高版本。
 
 
filesystem.getFileInfo() 返回关于文件或目录的信息
语法定义
 
filesytem.getFileInfo( path )
 
说明
此函数将会返回可描述传送给它的文件或目录的小对象。该对象拥有以下属性：
Size
IsDirectory
isHidden
lastModified
虽然有 isDirectory 函数，这个信息也会附有该花絮以存放来回传递文件树形结构所需之文件系
统作业数目。
 
范例
info = filesystem.getFileInfo( "myfile.txt" );
print( "myfile is " + bytesToUIString( info.size ) + " in size" );
 
可用性
适用于 2.0 版或更高版本。
 
 

filesystem.getRecycleBinInfo() filesystem.getTrashInfo() 取得关于已经删除但尚未清除的文件的信息
语法定义
filesystem.getRecycleBinInfo()
filesystem.getTrashInfo()
说明
 
获取用户的回收站或资源回收筒中的文件数量与总计大小。含两个成员的对象将会被返回，即
numItems 与 size。
 
此函数有两个名称，以反应出在两个平台 (Windows 与 Mac OS X) 上所使用的不同用语。
 
范例
mytrash = filesystem.getRecycleBinInfo();
mesg = myTrash.numItems + " items (" + myTrash.size +
" bytes)";
可用性
 
适用于 1.8 版或更高版本。
 
 
filesystem.isDirectory() 判断指定的路径是否为目录
语法定义
filesystem.isDirectory(path)
 
说明
如果指定的 path 是目录，则返回 true，否则将会返回 false。
 
范例
isDir = filesystem.isDirectory(path);
 
可用性
适用于 1.8 版或更高版本。
 
 
filesystem.itemExists() 判断指定的路径是否存在
语法定义
 
filesystem.itemExists(path)
 

说明
 
如果指定的 path 存在 (是文件或目录)，则返回 true，否则将会返回 false。
范例
 
exists = filesystem.itemExists(path);
 
可用性
 
适用于 1.8 版或更高版本。
 
 
 
fileystem.move() 将文件移动到位置上
语法定义
filesystem.move( path, destination );
 
说明
此函数可以让将文件移动到指定的目的地。来源可以是单一路径，或路径的数组。目的地必须是
存在的目录。如果成功，此函数将会返回 true，否则将会返回 false。
 
请注意，目前你无法使用此函数为文件重新命名。实际上，目前版本并没有重新命名的能力。
 
范例
filesystem.move( "myfile.txt", "/Users/evoas" );
 
可用性
适用于 2.0 版或更高版本。
 
filesystem.moveToRecycleBin() filesystem.moveToTrash() 将项目移动至回收站或资源回收筒中以将其
删除
语法定义
filesystem.moveToRecycleBin(files)
filesystem.moveToTrash(files)
 
说明
 
传送指定的一或多个文件 (提供「字符串」的一个数组来一次删除多个文件)。
 
此函数有两个名称，以反应出在两个平台 (Windows 与 Mac OS X) 上所使用的不同用语。
范例

filesystem.moveToTrash(myTmpFile);
 
可用性
 
适用于 1.8 版或更高版本。
 
filesystem.open() 根据其文件类型/后缀名来打开文件
语法定义
filesystem.open( path )
 
说明
可以使用此函数来以正确的应用程序打开任意文件。例如，将 Widget 文件路径传送到此函数中
将可在 Yahoo! Widget Engine 中打开 Widget (亦即，它将会如预期执行 Widget)。传入文件夹将可
在 Finder/Explorer 中打开它。
 
范例
filesystem.open( "PIM Overview.widget" );
 
可用性
适用于 2.0 版或更高版本。
 
filesystem.openRecycleBin() filesystem.openTrash() 在回收站/资源回收筒中打开包含项目的文件夹。
语法定义
filesystem.openRecycleBin() filesystem.openTrash()
 
说明
 
此函数等于按两下「回收站」或「资源回收筒」图示。它将会打开窗口以显示「回收站」/「资源
回收筒」的内容。
此函数有两个名称，以反应出在两个平台 (Windows 与 Mac OS X) 上所使用的不同用语。
 
范例
 
filesytem.openTrash();
 
可用性
 
适用于 2.0 版或更高版本。
 
 

filesystem.readFile() 将文本文件读入字符串或数组
语法定义
 
filesystem.readFile( path [,asLines] )
 
说明
 
此函数可用来将文本文件读入字符串或数组变量中。如果选用的第二个参数为 true，文件将被读
取并分成多行，且会返回这些行的数组。否则将只会返回内容的一个长字符串。
Widget Engine 能够读取大部分典型文本文件格式，但是读取 UTF-16 或 UTF-8 编码的格式效果
最佳。
 
范例
 
var data = filesystem.readFile( "myfile.txt" );
var lines = filesystem.readFile( "myfile.txt", true );
 
可用性
 
适用于 2.0 版或更高版本。
 
 
filesystem.reveal() 让系统的文件浏览器显示内容中的项目
语法定义
 
filesystem.reveal(path)
说明
使系统文件浏览器 (Windows 上的 Explorer、Mac OS X 上的 Finder) 显示包含已指定项目的目
录。此函数有助于将文件系统项目显示给用户。
范例
 
filesystem.reveal(myPath);
 
可用性
 
适用于 1.8 版或更高版本。
 
 
 

filesystem.volumes 目前已装载的磁盘区的数组
说明
 
filesystem 对象的磁盘区属性包含了所有目前已装设磁盘区的数组。数组中的每个项目皆是包含
以下属性的小对象：
 
Path
FreeBytes
totalBytes
 
可以搭配如 bytesToUIString 或 filesystem. GetDisplayName 等函数来使用这些项目。
 
范例
 
vols = filesystem.volumes;
for ( a in vols )
{
print( "Volume " +
 filesystem.getDisplayName( vols[a].path ) +
 " (path " + vols[a].path + ") has a capacity of " +
 bytesToUIString( vols[a].totalBytes ) + " and " +
 bytesToUIString( vols[a].freeBytes ) + " free." );
}
 
可用性
 
适用于 2.0 版或更高版本。
 
 
 
filesystem.writeFile() 将字符串或数组写入文本文件中
语法定义
 
filesystem.writeFile( path, string | array )
 
说明
此函数将会写出一个文件，内含一个字符串或字符串数组。如果指定了字符串，数据将会直接写
出。如果已传送数组，数据会以换行字符 "/n" 分隔的方式写出。目前，此函数始终以 UTF-8 格式写
入文件。
 
范例
 
filesystem.writeFile( "myfile.txt", myData );

可用性
适用于 2.0 版或更高版本。
 
 
screen关于显示的信息
属性 (Attributes)
 AvailHeight
 AvailLeft
 AvailTop
 AvailWidth
 ColorDepth
 Height
 PixelDepth
 Resolution
 width
 
语法定义
screen
 
说明
screen 对象拥有描述目前屏幕量制的不同属性 (Widget 主窗口一般所在的显示画面)。关于得个
别属性的详细信息，请参见以下说明。
 
范例
for (a in screen)
print("screen." + a + ": " + eval("screen." + a));
 
 
 
screen.availHeight目前屏幕的可用高度
语法定义
screen.availHeight
 
说明
 
大部分 Widget 窗口在屏幕上占用的垂直可用像素。此数值将会忽略如系统菜单列与 Dock 等项
目所占用的空间。
 
范例
myWindow.vOffset = screen.availHeight - 30;
 
 

screen.availLeft屏幕上最左边的可用位置
语法定义
screen.availLeft
 
说明
 
大部分 Widget 窗口在屏幕左侧占用的第一个可用位置，并没有被例如 Dock 等系统功能占用。
 
范例
myWindow.hOffset = screen.availLeft + 30;
 
 
 
screen.availTop屏幕上最上方的可用位置
语法定义
 
screen.availTop
 
说明
 
大部分 Widget 窗口在屏幕上方占用的第一个可用位置，并没有被例如菜单列等系统功能占用。
 
范例
myWindow.vOffset = screen.availTop + 10;
 
 
screen.availWidth 目前屏幕的可用宽度
语法定义
 
screen.availWidth
 
说明
 
大部分 Widget 窗口在屏幕上占用的垂直可用像素。此数值将会忽略如 Dock 等系统功能所占用
的空间。
 
范例
myWindow.width = screen.availWidth / 4;
 

大部分 Widget 窗口在屏幕上占用的每一个可用像素的位数。
 
范例
alert("Bits per pixel: " + screen.colorDepth);
 
 
screen.height目前屏幕的高度
语法定义
screen.height
 
说明
 
大部分 Widget 窗口在屏幕上占用的垂直可用像素。通常，screen.availHeight 将可提供测量屏
幕高度更有用的方法。
 
范例
myWindow.vOffset = screen.availHeight - 30;
 
 
 
screen.pixelDepth目前屏幕的色彩深度
语法定义
screen.pixelDepth
 
说明
大部分 Widget 窗口在屏幕上占用的每一个可用像素的位数。这是 screen.colorDepth 的同义
字，且专门针对兼容性提供。
 
范例
alert("Bits per pixel: " + screen.pixelDepth);
 
screen.colorDepth目前屏幕的色彩深度
语法定义
screen.colorDepth
 
说明

screen.resolution目前屏幕的分辨率
语法定义
screen.resolution
说明
大部分 Widget 窗口所占用的屏幕点阵分辨率，单位为每英吋点数 (dpi)。
范例
alert("Screen resolution: " + screen.resolution);
screen.width
目前屏幕的宽度
语法定义
screen.width
说明
大部分 Widget 窗口在屏幕上占用的水平可用像素。通常，screen.availWidth 将可提供测量屏
幕宽度更有用的方法。
范例
myWindow.hOffset = screen.width - 80;
 
 
system关于机器或环境的信息
属性 (Attributes)
 
 airport/wireless
 appearance
 battery
 clipboard
 cpu
 event
 languages
 memory
 mute
 platform
 volume
 widgetDataFolder
 userDocumentsFolder
 userDesktopFolder
 userPicturesFolder
 userMoviesFolder
 userMusicFolder
 userWidgetsFolder
 applicationsFolder
 temporaryFolder
 trashFolder
 

说明
 
system 对象是关于你所执行的机器或环境某些方面的项目的接口。例如，可以取得有关电池状态
或无线联机的信息 (如果有的话)。
 
 
 
system.airport system.wireless 存取 WiFi/AirPort 信息的内置支持
属性 (Attributes)
available
如果安装了 WiFi/AirPort，则为 true。
info
WiFi/AirPort 状态的摘要。
network
目前网络的名称。
noise
联机的噪声程度。
powered
如果已打开 WiFi/AirPort 电源，则为 true。
signal
联机的信号等级。
 
说明
 
已安装的 WiFi/AirPort 网络卡的设定值与状态可通过 system.airport 或 system.wireless 对
象使用。
WiFi/AirPort Widget 可以更广泛地使用此对象。
 
范例
if (system.airport.available && system.airport.powered)
alert("Current network is " + system.airport.network);
if(system.wireless.available && system.wireless.powered)
alert("Current network is "+ system.wireless.network);
 
 
system.airport.available system.wireless.available 判断是否已安装 WiFi/AirPort (或其它兼容的无线
网络卡)
语法定义
system.airport.available system.wireless.available
 
说明
available 属性将会返回布尔 true/false 数值，其对应于可连接网络的无线装置的可用性。
 
范例
if (! system.airport.available)
signal_status.src = "NoCard.png";

else
signal_status.src = "Signal.png";
if (! system.wireless.available)
signal_status.src = "NoCard.png";
else
signal_status.src = "Signal.png";
 
参见
system.airport.signal, system.wireless.signal
system.airport.info
system.wireless.info
 
WiFi/AirPort 状态摘要
语法定义
 
system.airport.info system.wireless.info
 
说明
WiFi/AirPort 状态的简要、可以让人容易阅读的说明。
 
范例
alert(system.airport.info);
alert(system.wireless.info);
 
system.airport.network system.wireless.network 返回目前 WiFi/AirPort 网络的名称
语法定义
system.airport.network system.wireless.network
 
说明
此属性包含目前 WiFi/AirPort 网络的名称 (若有的话)。
 
范例
alert("AirPort network " + system.airport.network + " in use");
 
alert("WiFi network " + system.wireless.network + " in use");
 
system.airport.noise system.wireless.noise
目前 WiFi/AirPort 联机的噪声程度
 

语法定义
system.airport.noise system.wireless.noise
说明
 
此属性包含可表示目前 WiFi/AirPort 联机上噪声程度的数值。
此数值通常是不可靠的。
 
范例
if (system.airport.noise > 20)
status.src = "noisy.png";
if (system.wireless.noise > 20)
status.src = "noisy.png";
 
Windows 注意事项
 
此属性在 Windows 上总是为零。
 
system.airport.powered system.wireless.powered
指示 WiFi/AirPort 网络卡是否打开或关闭的布尔
 
语法定义
system.airport.powered system.wireless.powered
 
说明
此布尔变量将会指出 WiFi/AirPort 目前是否已打开或关闭。使用此变量可决定是否存取其它
WiFi/AirPort 状态属性。
 
范例
if (system.airport.available && system.airport.powered)
alert("Current network is " + system.airport.network);
if(system.wireless.available && system.wireless.powered)
alert("Current network is "+ system.wireless.network);
 
system.airport.signal system.wireless.signal
返回目前 WiFi/AirPort 联机的信号强度
 
语法定义
system.airport.signal
system.wireless.signal
 
说明
WiFi/AirPort 对象的 signal 属性可以返回对应于装置所连接的无线网络信号强度的数值。

 
请注意，在此版本的 Widget Engine 中，信号强度范围是 0-75，且不是对于 Apple 信号强度的
线性对映。
 
范例
theStrength = system.airport.signal;
if ( theStrength =&lt; 33 )
signalBars.src = "halfFull.png"
theStrength = system.wireless.signal;
if ( theStrength =&lt; 50 )
signalBars.src = "halfFull.png"
 
system.appearance目前系统的外观
 
语法定义
 
system.appearance
 
说明
 
目前系统的外观。对于 Mac OS X 10.3 而言，这将只能是 Blue 或 Graphite。
 
如果 Widget 使用了你想让目前「Mac OS X 外观」特有的图片，你只需使用此变量来取得执行中
的「外观」，并适当地调整 图片来源文件即可。
 
请注意，这样将会返回前缀大写的文字，因此请确保测试文字为 "Blue" 与 "Graphite"，而非
"blue" 与 "graphite"。
 
注意：在此版本的 Widget Engine 中，我们不支持对 Widget 通知「外观」的改变。
 
在 Windows 上，始终会返回数值 Blue。
 
范例
 
if (system.appearance == "Graphite")
header.src = "graphiteHeader.png";
else
header.src = "aquaHeader.png";
 
system.battery 存取电池与 UPS 信息的内置支持
语法定义
system.battery

 
说明
电池数是以 0 为基底的数组。单颗电池的笔记型计算机将一定是 battery[0]，但是当在使用两
颗电池的计算机上执行时，预期的主电池槽会登录为电池 1，而选用的电池槽则会登录为电池 0。安
装在目前系统中的电池数可在 system.BatteryCount 中使用。
 
注意：在此版本的 Widget Engine 中，Windows 上只支持一颗电池 (但是，关于它的信息则是系
统中所有电池的总计)。
 
system.battery[n].currentCapacity 电池电量
语法定义
system.battery[batteryNumber].currentCapacity
 
说明
目前电池电量百分比。
 
system.battery[n].isCharging 充电状态
语法定义
system.battery[batteryNumber].isCharging
 
说明
如果电池正在充电，则为 true (亦即，电池容量低于 100%，且系统插头已插入 AC 电源中)。
 
system.battery[n].isPresent 是否已安装电池
语法定义
system.battery[batteryNumber].isPresent
 
说明
 
如果电池实际上已存在，则为 true。
 
system.battery[n].maximumCapacity 电池的最大电量
语法定义
system.battery[batteryNumber].maximumCapacity
 
说明

电池的最大容量 (由于容量以百分比表示，因此此数值始终为 100)。
 
system.battery[n].name 电池名称
语法定义
system.battery[batteryNumber].name
 
说明
电池的可以供人阅读的名称。
 
system.battery[n].powerSourceState 目前的电源
语法定义
 
system.battery[batteryNumber].powerSourceState
 
说明
根据系统插头是否已经插入电源插座来返回「AC 电源」或「电池电源」。
system.battery[n].timeToEmpty
电池放电完成剩余的分钟数
 
语法定义
system.battery[batteryNumber].timeToEmpty
 
说明
此数值以分钟数表示。-1 数值表示系统仍在判断电池电量耗尽的速度 (这又称为「计算」阶段)。
 
system.battery[n].timeToFullCharge 电池全部充电完成剩余的分钟数
语法定义
system.battery[batteryNumber].timeToFullCharge
说明
 
此数值以分钟数表示。-1 数值表示系统仍在判断电池的充电速度 (这又称为「计算」阶段)。
请注意，currentCapacity 通常是判断电池充电量更可靠的依据。
 
范例
alert(system.battery[0].timeToFullCharge + ' minutes to full
charge');
 

system.battery[n].transportType 电池通讯频道
语法定义
system.battery[batteryNumber].transportType
 
说明「内部」或 UPS 通讯的方法
system.batteryCount已安装的电池数目
语法定义
system.batteryCount
 
说明
 
已安装在目前系统中的电池数目可在 system.batteryCount 中使用。
通常此数目为 1，但是某些笔记型计算机支持更多的电池数，因此一些准备使用多颗电池的
Widget 应考虑到此情况。
 
范例
for (b = 0; b < system.batteryCount; b++)
totalTime += system.battery[b].timeToEmpty;
 
Windows 注意事项
 
目前此属性的数值一定为 1 (但会已提出所有电池的可用电源报告)。
 
system.clipboard 存取目前的系统剪贴版
语法定义
system.clipboard
 
说明
system.clipboard 包含系统剪贴版上的文字 (如果有的话)。设定此属性将会在系统剪贴版中加
载该数据，并移除之前位于剪贴版中的任何内容。
 
范例
myText = system.clipboard;
myNewText = "--<(" + myText + ")>--";
system.clipboard = myNewText;
 

system.cpu包含关于目前 CPU 负载的信息
语法定义
system.cpu
 
说明
system.cpu 是包含可摘要系统 CPU 的活动层级的数个成员的对象 (成员的详细信息如下)。
请注意，搜集此数据的基础机制分辨率为 1 秒钟，因此，它的速度与此信息改变的速度一样快。
亦即，每秒钟多于一次地轮寻 system. cpu 是没有用的。
 
范例
 
for (a in system.cpu)
print("system.cpu." + a + ": " + eval("system.cpu." + a));
 
 
system.cpu.activity返回关于目前 CPU 活动的信息
语法定义
system.cpu.activity
 
说明
system.cpu.activity 包含目前 CPU 负载的百分比。如果计算机十分忙碌，此数值将会接近 100。
它是其它 system.cpu 成员 user、sys 与 nice 的总和。它会将机器负载当成一个整体来表示，而不
管它拥有多少个处理器。
 
范例
load = system.cpu.activity;
 
system.cpu.idle返回关于闲置 CPU 的信息
语法定义
system.cpu.idle
说明
system.cpu.idle 将会提供可负担更多工作的 CPU 的测量结果。其以百分比计。
 
范例
idle_percent = system.cpu.idle;
 
 

system.cpu.nice返回关于提升的优先权 CPU 循环的信息
语法定义
system.cpu.nice
 
说明
 
system.cpu.nice 是优先权已经提升的工作所占用的 CPU 工作量的测量结果 (正常处理程序将会
报告为 system.cpu.user)。
 
范例
priorityTasks = system.cpu.nice;
 
Windows 注意事项
此属性的数值一定是零。
 
system.cpu.numProcessors返回系统中的处理器数目
语法定义
system.cpu.numProcessors
 
说明
system.cpu.numProcessors 将会指出目前系统中的处理器数目。
 
范例
if (system.cpu.numProcessors == 2)
system = "Dualie";
 
system.cpu.sys返回关于系统 CPU 的信息
语法定义
system.cpu.sys
 
说明
system.cpu.sys 包含系统工作占用 CPU 的百分比 (相对于用户工作)。
 
范例
systemTime = system.cpu.sys;
 
 

system.cpu.user返回关于用户 CPU 的信息
语法定义
system.cpu.user
 
说明
system.cpu.user 是一般工作所占用的 CPU 工作量的测量结果 (相对于系统工作)。
 
范例
 
userTasks = system.cpu.user;
 
范例
 
userTasks = system.cpu.user;
 
 
system.event关于已接收的上一个事件的信息
语法定义
system.event
 
说明
system.event 包含关于 Widget 已接收的上一个事件的各种信息 (通常为如点击鼠标的用户动作
结果)。要了解详细信息，请参见以下内容。
范例
 
for (a in system.event)
 print("system.event." + a + ": " + eval("system.event." + a));
 
system.event.hOffset, system.event.vOffset窗口坐标中的鼠标位置
语法定义
system.event.hOffset, system.event.vOffset
 
说明
system.event.hOffset 与 system.event.vOffset 内含与 Widget 窗口有关的坐标的鼠标位置。
该数值可在任何 JavaScript 内容中存取，因此该数值有可能位于 Widget 窗口以外 (但它们仍
然与 Widget 窗口有关)。
 
范例
print("Mouse: " + system.event.hOffset + ", " +
system.event.hOffset);

 
 
system.event.key已触发目前事件的按键
语法定义
system.event.key
 
说明
system.event.key 包含已按下的按键。
 
范例
print("Key: " + system.event.key);
 
参见
system.event.keyString
 
system.event.keyString已触发目前事件的按键名称
语法定义
system.event.keyString
 
说明
system.event.keyString 包含已按下按键的名称，亦即特殊按键的名称，例如 "PageUp" 或一般
按键的 16 进位值。
 
范例
print("Key Name: " + system.event.keyString);
 
参见
system.event.key
 
 
 
system.event.modifiers目前按键事件的辅助按键状态
语法定义
system.event.modifiers
 
说明
system.event.modifiers 包含正在处理按键事件时的辅助按键 (在 onKeyDown 或 onKeyUp
中)。它可以是以下组合之一：
shift, capslock, control, option, numlock, help, fkey

例如：
shift+control
 
范例
print("Modifiers: " + system.event.modifiers);
 
system.event.screenX, system.event.screenY屏幕坐标中的鼠标位置
语法定义
system.event.screenX, system.event.screenY
 
说明
system.event.screenX 与 system.event.screenY 内含屏幕坐标的鼠标位置。
 
范例
print("Mouse: " + system.event.screenX + ", " +
system.event.screenY);
 
 
system.event.scrollDelta返回鼠标滚轮移动的 delta 值
语法定义
system.event.scrollDelta
 
说明
system.event.scrollDelta 包含你应该滚动的行数，正或负数。此数值只在 onMouseWheel 句柄
期间有效。
 
范例
frame.scrollY += (system.event.scrollDelta * 10);
 
system.event.timestamp事件发生的时间
语法定义
system.event.timestamp
 
说明
system.event.timestamp 包含可记录事件发生时间的 Date 对象 (相对于由 JavaScript 处理的
时间)。此对象可用于各种事件，例如决定按住按键的时间长度。
 
范例
print("Event happened at: " + system.event.timestamp);

Windows 注意事项
 
2.1.1 版可在 Windows 上使用。
 
 
system.event.x, system.event.y坐标中的鼠标位置
语法定义
system.event.x, system.event.y
 
说明
system.event.x 与 system.event.y 内含与目前对象 (动作已被触发的对象) 相关的坐标的鼠标
位置。
范例
print("Mouse: " + system.event.x + ", " +
system.event.y);
 
 
system.languages返回用户偏好的语言设定
语法定义
system.languages
 
说明
system.languages 包含用户已在「国际系统偏好设置」面板中指定的语言清单。元素 0 是他们
的主要语言，1 是他们的第二个选择，依此类推。
只能读取此设定，除非使用「系统偏好设置」面板，否则它无法改变。
 
范例
print("system.languages: " + system.languages);
system.languages: en,de,ja,fr,nl,it,es,zh_TW
 
system.memory关于机器实体/虚拟内存的信息
属性 (Attributes)
AvailPhysical
AvailVirtual
Load
TotalPhysical
totalVirtual
 
说明

可以通过此系统对象来检查机器上内存的容量。请注意，目前两个平台上的虚拟内存数目都有些
可疑。
 
system.memory.availPhysical可用物理内存的数量
说明
 
返回可用物理内存的字节数目。如果要的话，可以使用 bytesToUIString 来将其变为更容易使用
的项目。
 
范例
print( "available RAM: " +
bytesToUIString( system.memory.availPhysical ) );
 
可用性
适用于 2.0 版或更高版本。
 
isystem.memory.availVirtual可用虚拟内存的数量
说明
 
返回可用虚拟内存的字节数目。如果要的话，可以使用 bytesToUIString 来将其变为更容易使用
的项目。
 
范例
print( "avail virtual memory: " +
bytesToUIString( system.memory.availVirtual ) );
可用性
 
适用于 2.0 版或更高版本。
 
注意事项
 
目前此数目并不十分精确，尤其在 Windows 上。
 
system.memory.load已使用内存的百分比
说明
返回从 0 至 100 的数字，它表示正在使用中的实体 RAM 的目前数量。
 
范例
print( "current system load: " +

system.memory.load + "%" );
 
可用性
适用于 2.0 版或更高版本。
 
 
system.memory.totalPhysical已安装的实体 RAM 数量
说明
回已安装物理内存的字节数目。如果要的话，可以使用 bytesToUIString 来将其变为更容易使用
的项目。
 
范例
print( "Installed RAM: " +
bytesToUIString( system.memory.totalPhysical ) );
 
可用性
适用于 2.0 版或更高版本。
 
 
 
system.memory.totalVirtual总虚拟内存数量
说明
返回总虚拟内存的字节数目。如果要的话，可以使用 bytesToUIString 来将其变为更容易使用的
项目。
范例
print( "total virtual memory: " +
bytesToUIString( system.memory.totalVirtual ) );
 
可用性
适用于 2.0 版或更高版本。
 
注意事项
目前此数目并不十分精确，尤其在 Windows 上。
 
 
system.mute设定系统的静音状态
 
语法定义
system.mute

 
说明
此变量可以反映出机器的声音是否为静音。将其设定为 true 可使系统声音为静音。
 
范例
// 找出机器是否为静音
if ( system.mute )
print("What? I can't hear you!");
else
print("I can hear sounds from my Mac!");
// 关闭系统声音
system.mute = true;
 
 
system.platform 返回 Widget 正在其上执行的系统类型
语法定义
system.platform
 
说明
此变量包含目前 Widget 正在其上执行的平台。
范例
print("platform: " + system.platform);
 
在 Mac OS X 上的结果如下：
platform: macintosh
 
在 Windows 上的结果如下：
platform: windows
 
包含不同用户文件夹名称的系统变量
system.userDocumentsFolder
system.userDesktopFolder
system.userPicturesFolder
system.userMoviesFolder
system.userMusicFolder
system.userWidgetsFolder
system.applicationsFolder
system.temporaryFolder
system.trashFolder
 
语法定义
 

system.userDocumentsFolder system.userDesktopFolder system.userPicturesFolder
system.userMoviesFolder system.userMusicFolder system.userWidgetsFolder
system.applicationsFolder system.temporaryFolder system.trashFolder
 
说明
 
这些变量包含不同用户中心及系统文件夹的路径。使用这些变量，正确的位置便可通过平台独立
的方式决定。
 
范例
print("userMusicFolder: " + system.userMusicFolder);
 
在 Mac OS X 上的结果如下：
userMusicFolder: /Users/joe/Music
 
在 Windows 上的结果如下：
userMusicFolder:
c:/Documents and Settings/joe/My Documents/My Music
 
system.volume取得或设定系统音量
语法定义
system.volume
 
说明
此变量可反映出目前的音量。将此变量设定为 0 与 16 之间的数字可改变系统音量。将音量设定
为 0 (零) 与将 system.mute 设定为 true 的效果相同。
 
范例
// 将音量设定为 50%
system.volume = 8;
 
system.widgetDataFolder Widget 可以安全存放数据的文件夹
语法定义
system.widgetDataFolder
 
说明
此变量包含用户硬盘上的文件夹名称，其中永久数据 (甚或需要短时间快取的数据) 可由 Widget
安全存放。长久以来，Widget 已经尝试将数据存放在它自己的包中，但是此操作方法中有许多缺点，
主要的缺点是位置可能无法写入。每个 Widget 皆可取得如果尚未存在便会建立的不同文件夹。
 
范例
saveFileName = system.widgetDataFolder + "/data";

 
平台注意事项
 
在 Mac 上，此文件夹的位置是 "~/Library/Application Support/ Konfabulator/Widgets"。在
PC 上，其位于 "C:/Documents and Settings/ <user>/Local Settings/Application
Data/Yahoo/Widget Engine/Widget Data" 中
 
应用程序属性与函数
 
这将会为 JavaScript 程序代码提供允许远程控制与获取数据的某些应用程序的存取权。
目前唯一支持的应用程序是 iTunes (Windows 与 Mac OS X 版本皆可自
http://www.apple.com/itunes 中取得)。
 
 
iTunes取得 iTunes 中的信息以及与 iTunes 互动
语法定义
iTunes
 
说明
iTunes 对象允许远程控制并显示 iTunes 曲目与歌手的信息。关于个别函数与属性的详细信息，
请参见以下内容。
 
可用性
iTunes 对象适用于 1.8 版或更高版本。
 
 
iTunes.backTrack() 通知 iTunes 移至上一个曲目
语法定义
iTunes.backTrack()
说明
通知 iTunes 移至上一个曲目。
 
范例
iTunes.backTrack();
 
参见
iTunes.nextTrack()
 

iTunes.fastForward() 通知 iTunes 在目前曲目中向前快转
语法定义
iTunes.fastForward()
 
说明
通知 iTunes 在目前曲目中往前跳。
 
范例
iTunes.fastForward();
 
参见
iTunes.rewind()
 
 
iTunes.nextTrack()通知 iTunes 移至下一个曲目
语法定义
iTunes.nextTrack()
 
说明
通知 iTunes 移至下一个曲目。
 
范例
iTunes.nextTrack();
 
参见
iTunes.backTrack()
 
 
iTunes.pause()通知 iTunes 暂停播放
语法定义
iTunes.pause()
 
说明
通知 iTunes 暂停播放。
 
范例
iTunes.pause();
 
参见
iTunes.resume()

 
 
iTunes.play() 通知 iTunes 开始播放目前曲目
语法定义
iTunes.play()
 
说明
通知 iTunes 播放目前曲目。
 
范例
iTunes.play();
参见
iTunes.pause()
 
 
iTunes.playPause() 通知 iTunes 在播放与暂停之间切换
语法定义
iTunes.playPause()
 
说明
如果 iTunes 目前已暂停，则通知它播放，或者如果 iTunes 目前正在播放，则通知它暂停。
 
范例
iTunes.playPause();
 
iTunes.playerPosition 返回目前曲目中的目前位置
语法定义
iTunes.playerPosition
 
说明
此属性将会返回目前正在播放曲目中的目前位置 (以秒为单位)。设定它可将播放位置移动至曲目
中的指定秒数。
 
范例
iTunes.playerPosition;
 
 

iTunes.playerStatus 返回描述 iTunes 目前状态的字符串
语法定义
iTunes.playerStatus
 
说明
此属性将会返回以下字符串之一：已停止、已暂停、正在播放、向前快转、倒带或未知。
 
范例
currentState = iTunes.playerStatus;
 
 
iTunes.random iTunes.shuffle
反映出 iTunes 的随机数播放状态
 
语法定义
iTunes.random
 
说明
此属性可以反映出 iTunes 的随机数播放状态。如果目前的播放清单设定为随机数播放，则其为
true，否则为 false。设定该属性将可改变 iTunes 的随机数播放状态。
 
范例
iTunes.random = 1;
shuffleState = iTunes.shuffle;
 
 
iTunes.repeatMode 指示 iTunes 目前的重复模式
语法定义
iTunes.repeatMode
 
说明
此属性将会返回以下字符串之一：off、one 或 all 以指出目前的重复模式。重复模式可通过将
属性设定为这些字符串之一来设定。
 
范例
mode = iTunes.repeatMode;
 
iTunes.repeatMode = 'off';
 
 

iTunes.resume() 通知 iTunes 恢复播放
语法定义
iTunes.resume()
 
说明
通知 iTunes 于暂停之后恢复播放。
 
范例
iTunes.resume();
 
参见
iTunes.pause()
 
iTunes.rewind() 通知 iTunes 往回跳
语法定义
iTunes.rewind()
 
说明
通知 iTunes 在目前曲目中往回跳。
 
范例
iTunes.rewind();
 
参见
iTunes.fastForward()
 
 
iTunes.running 返回 iTunes 目前是否正在执行
语法定义
iTunes.running
 
说明
使用此属性可判断 iTunes 目前是否正在执行。
 
范例
iTunes.running;
 
 

iTunes.stop() 通知 iTunes 停止播放
语法定义
iTunes.stop()
 
说明
通知 iTunes 停止播放。
 
范例
iTunes.stop();
参见
iTunes.play()
 
 
iTunes.streamURL 返回目前正在播放的流的 URL
语法定义
iTunes.streamURL
 
说明
如果 iTunes 目前正在播放声音流媒体，此属性将会包含流媒体的 URL。
 
范例
url = iTunes.streamURL;
 
 
iTunes.trackAlbum 返回目前专辑的名称
语法定义
iTunes.trackAlbum
 
说明
此属性包含目前专辑的名称 (如果已知)。如果正在播放流媒体，流媒体的名称将会显示在此。
 
范例
currAlbum = iTunes.trackAlbum;
 
 
iTunes.trackArtist 返回目前正在播放的曲目的歌手
语法定义

iTunes.trackArtist
 
说明
此属性包含目前专辑的歌手姓名 (如果已知)。如果正在播放流媒体，此信息将无法使用。
 
范例
iTunes.trackArtist;
 
 
iTunes.trackLength 返回目前曲目的长度
语法定义
iTunes.trackLength
 
说明
此属性包含目前正在播放的曲目的长度。如果正在播放流媒体，此信息将无法使用。
 
范例
len = iTunes.trackLength;
 
 
iTunes.trackRating目前曲目的分级
语法定义
iTunes.trackRating
 
说明
此属性包含目前正在播放曲目的分级。设定该属性将可改变 iTunes 中目前曲目的分级。如果正
在播放流媒体，此信息将无法使用。
 
范例
rating = iTunes.trackRating;
 
 
iTunes.trackTitle 返回目前曲目的标题
语法定义
iTunes.trackTitle
 
说明
此属性包含目前正在播放的曲目的标题。如果正在播放流媒体，此信息可能无法使用。
范例

title = iTunes.trackTitle;
 
 
iTunes.trackType 返回目前曲目的类型
语法定义
iTunes.trackType
 
说明
此属性包含目前正在播放的曲目的类型。它可以包括以下类型之一：audio file、audio cd track、
audio stream、audio device、shared library 或 unknown
 
范例
tt = iTunes.trackType;
 
 
iTunes.version 返回 iTunes 的版本
语法定义
iTunes.version
 
说明
此属性包含正受到控制的 iTunes 的复制版本。
 
范例
log("iTunes Version: " + iTunes.version);
 
 
iTunes.volume iTunes 播放的音量
语法定义
iTunes.volume
 
说明
此属性反映出 iTunes 正在播放的音量。它可以在 0 与 100 之间变化。为该属性指定数值将可
改变音量。
 
范例
iTunes.volume = 60;
 
 

Widget Engine 对象属性与函数
本节包含了未在 XML 一节中介绍到的 Javascript 函数与属性。
 
Frame 属性与函数
Frame.addSubview()
将视图做为子视图加到框体中
 
语法定义
void Frame.addSubview( object );
 
说明
此函数可将对象加到框体中。目前的 Image、Text、TextArea、Frame 与 ScrollBar 对象可做为
子件加到框体对象中。
 
范例
myFrame.addSubview( myImage );
 
可用性
适用于 3.0 版或更高版本。
 
Frame.home() 将框体滚动至左上方
语法定义
void Frame.home();
 
说明
此函数基本上可将 scrollX 与 scrollY 属性设定为 0, 0。
范例
myFrame.home();
 
可用性
适用于 3.0 版或更高版本。
Frame.hScrollBar框体的水平滚动条
语法定义

Frame.hScrollBar
 
说明
可以使用此属性来设定或查询框体的水平滚动条。附加滚动条将会自动设定以便在框体与滚动条
之间进行通讯。
 
范例
myFrame.hScrollBar
 
可用性
适用于 3.0 版或更高版本。
 
 
Frame.end() 将框体滚动至左下方
语法定义
void Frame.end();
 
说明
此函数可将框体滚动至其内容的下方。
 
范例
myFrame.end();
 
可用性
适用于 3.0 版或更高版本。
 
 
Frame.lineDown() 向下滚动一行框体
语法定义
void Frame.lineDown();
 
说明
此函数可依照框体的 vLineSize 属性所指定的数量来向下滚动一行框体。
 
范例
myFrame.lineDown();
 
可用性
适用于 3.0 版或更高版本。
 
 

Frame.lineLeft() 向左滚动一行框体
语法定义
void Frame.lineLeft();
 
说明
此函数可依照框体的 hLineSize 属性所指定的数量来向左滚动一行框体。
 
范例
myFrame.lineLeft();
 
可用性
适用于 3.0 版或更高版本。
 
Frame.lineRight() 向右滚动一行框体
语法定义
void Frame.lineRight();
 
说明
此函数可依照框体的 hLineSize 属性所指定的数量来向右滚动一行框体。
 
范例
myFrame.lineRight();
 
可用性
适用于 3.0 版或更高版本。
 
Frame.lineUp() 向上滚动一行框体
语法定义
 
void Frame.lineUp();
说明
 
此函数可依照框体的 vLineSize 属性所指定的数量来向上滚动一行框体。
范例
 
myFrame.lineUp();
 
可用性
适用于 3.0 版或更高版本。
 

 
Frame.pageDown() 向下滚动一个页面框体
语法定义
void Frame.pageDown();
 
说明
此函数可将框体往下滚动一页，其滚动高度为框体的高度减去 vLineHeight 指定的一个行高。
 
范例
myFrame.pageDown();
 
可用性
适用于 3.0 版或更高版本。
 
 
Frame.pageLeft() 向左滚动一个页面框体
语法定义
void Frame.pageLeft();
 
说明
此函数可将框体往左滚动一页，其滚动宽度为框体的宽度减去 hLineHeight 指定的一个行高。
 
范例
myFrame.pageLeft();
 
可用性
适用于 3.0 版或更高版本。
 
 
Frame.pageRight()向右滚动一个页面框体
语法定义
void Frame.pageRight();
 
说明
此函数可将框体往右滚动一页，其滚动宽度为框体的宽度减去 hLineHeight 指定的一个行高。
 
范例
myFrame.pageRight();
 

可用性
适用于 3.0 版或更高版本。
 
 
Frame.pageUp()向上滚动一个页面框体
语法定义
void Frame.pageUp();
 
说明
此函数可将框体往上滚动一页，其滚动高度为框体的高度减去 vLineHeight 指定的一个行高。
 
范例
myFrame.pageUp();
 
可用性
适用于 3.0 版或更高版本。
 
Frame.removeFromSuperview() 从父视图中清除对象
语法定义
void Frame.removeFromSuperview()
 
说明
使用此方法可从窗口中移除对象。你可能会因为已经完成这个动作并重新加载了新信息而这样做。
清除之后，就可以将其设定为空来只清除对它的应用，如果你愿意的话，也可以将它放入其它窗口或
框体中。
当将 Widget 的最低版本设定为 3.0 版时，必须调用它以从窗口中移除对象。删除应用是没有用
的。
 
范例
myObject.removeFromSuperview();
 
可用性
适用于 3.0 版或更高版本。
 
 
Frame.subviews此框体中的子视图数组
语法定义
array Frame.subviews (read-only)
 

说明
此属性包含这个框体中所含有的所有视图，例如 Javascript 数组。如果此框体没有子视图，则
此属性将会设定为空。
 
范例
var x = myFrame.subviews[0];
 
可用性
适用于 3.0 版或更高版本。必须至少将 Widget 的最低版本设定为 3.0 版才能使此属性存在。
 
Frame.superview此视图的父视图
语法定义
frame|root Frame.superview (read-only)
 
说明
此属性包含这个视图的父视图。父视图可以是「框体」对象或「根」对象。如果此视图没有父视
图，则此属性将会设定为空。
 
范例
var parent = myFrame.superview;
可用性
适用于 3.0 版或更高版本。必须至少将 Widget 的最低版本设定为 3.0 版才能使此属性存在。
 
 
Frame.vScrollBar框体的垂直滚动条
语法定义
Frame.vScrollBar
 
说明
可以使用此属性来设定或查询垂直滚动条。附加滚动条将会自动设定以便在框体与滚动条之间进
行通讯。
 
范例
myFrame.vScrollBar
 
可用性
 
适用于 3.0 版或更高版本。
Image 属性与函数
 

Image.fade()淡入或淡出图片
语法定义
Image.fade(start, end, duration)
 
说明
fade() 命令将会导致图片从开始透明度淡出到结束透明度。duration 可以指定要动画持续的时
间 (以十分之一秒为单位)。
 
范例
newOpacity = 0;
myImage.fade(myImage.opacity, newOpacity, 1);
 
 
Image.moveTo()通过动画将图片从点 a 移到点 b
语法定义
Image.moveTo(newX, newY, duration)
 
说明
图片的原点 (hOffset, vOffset) 会移动到 newX 与 newY 指定的新坐标。duration 可以指定要
动画持续的时间 (以十分之一秒为单位)。对象的移动是以动画的形式表现的 (这跟只改变 hOffset
与 vOffset 不同)。
 
范例
myImage.moveTo(50, 50, 3);
 
 
Image.reload() 从磁盘中重新加载图片
语法定义
Image.reload()
 
说明
使用此方法可从磁盘中重新加载图片。如果 Widget 使用的是由外部程序不断更新的图形，则这
是特别有用的，因为它取消了「图片」对象的正常快取行为。
 
范例
 
myImage.reload();
 
 

Image.removeFromSuperview() 从父视图中卸离图片对象
语法定义
Image.removeFromSuperview()
 
说明
使用此方法可将图片对象从窗口中移除。你可能会因为已经完成这个动作并重新加载了新信息而
这样做。卸离之后，如果你已经完成，就可以将其设定为空来只清除对它的应用，或如果你愿意的话，
也可以将它放入其它窗口或框体中。
当将 Widget 的最低版本设定为 3.0 版时，必须调用它以从窗口中移除对象。删除应用是没有用
的。
 
范例
myImage.removeFromSuperview();
 
可用性
适用于 3.0 版或更高版本。
 
 
Image.slide() 以指定的方向与期间滑动显示图片
语法定义
Image.slide(direction, amountOfImageToConceal, duration)
 
说明
slide() 命令是一种用来隐藏与显示部分用户接口的动画效果。当要以特定方向滑动图片，并使
其消失在本身中，而不仅仅是移动时，便可使用此命令。duration 可以指定要动画持续的时间 (以十
分之一秒为单位)。
 
范例
myImage.slide("up,left", 50, 3);
 
Image.superview 此视图的父视图
语法定义
frame|root Image.superview (read-only)
 
说明
此属性包含这个视图的父视图。父视图可以是「框体」对象或「根」对象。如果此视图没有父视
图，则此属性将会设定为空。
 
范例
var parent = myImage.superview;

 
可用性
适用于 3.0 版或更高版本。必须至少将 Widget 的最低版本设定为 3.0 版才能使此属性存在。
 
 
Root 属性与函数
根是窗口中所有视图的容器。当例如图片的对象设定了它的窗口属性时，这便是内部加入的视图。
在这里，它是用于完成视图层次的，且只拥有两个属性及一个函数。根能够以它所属的窗口的属性来
存取。必须至少将 Widget 的最低版本设定为 3.0 版才能使此属性存在。
 
Root.addSubview() 将视图加到窗口的根中
语法定义
void Root.addSubview( object );
 
说明
此功能可将对象加到窗口的根视图中。目前的 Image、Text、TextArea、Frame 与 ScrollBar 对
象可新增为子件。
可以使用此方法或通过设定对象的 window 属性来将视图附加至窗口的顶层。两种方法皆可产生
相同结果。
 
范例
myWindow.root.addSubview( myImage );
 
可用性
适用于 3.0 版或更高版本。
 
 
Root.subviews 子视图的数组
语法定义
array Root.subviews (read-only)
 
说明
此属性包含这个视图中所含有的所有视图，例如 Javascript 数组。如果根没有子视图，则此属
性将会设定为空。
 
范例
var x = myWindow.root.subviews[0];
 

可用性
适用于 3.0 版或更高版本。
 
 
Root.superview 此视图的父视图
语法定义
null Root.superview (read-only)
 
说明
此属性包含这个视图的父视图。此属性始终返回空值。在这里，它用于完成层次性。
 
范例
var shouldBeNull = myWindow.root.superview;
 
可用性
适用于 3.0 版或更高版本。必须至少将 Widget 的最低版本设定为 3.0 版才能使此属性存在。
 
ScrollBar 属性与函数
ScrollBar.removeFromSuperview()从父视图中卸离对象
语法定义
ScrollBar.removeFromSuperview()
 
说明
使用此方法可将滚动条对象从窗口中移除。你可能会因为已经完成这个动作并重新加载了新信息
而这样做。卸离之后，如果你已经完成，就可以将其设定为空来只清除对它的应用，或如果你愿意的
话，也可以将它放入其它窗口或框体中。
当将 Widget 的最低版本设定为 3.0 版时，必须调用它以从窗口中移除对象。删除应用是没有用
的。
 
范例
myScrollbar.removeFromSuperview();
 
可用性
适用于 3.0 版或更高版本。
 
 

ScrollBar.setRange()设定滚动条的最小及最大值
语法定义
ScrollBar.setRange(int min, int max)
 
说明
使用此方法来定义可由滚动条表示的值的范围。你无法直接修改最小与最大属性，因此必须使用
此函数来设定那些属性。如果调用此函数时这个值超出了新范围，则将会将此值固定在这个范围中。
如果你正将滚动条附加到框体对象中，则通常情况下将无须处理此函数。如果是这样，则将会为
你自动设定范围。
 
范例
myScrollbar.setRange(0, 100);
可用性
 
适用于 3.0 版或更高版本。
 
 
ScrollBar.setThumbInfo()取代构成滚动条的滚动方块的图片
语法定义
 
ScrollBar.setThumbInfo(int offset, string|array images )
 
说明
 
虽然标准滚动条对象允许你自订滚动方块色彩，但可能无法满足所有 Widget 的需要。要进行更
多自订，可以将一或三个图片路径分别做为字符串或数组传送给此函数，滚动方块将使用那些图片来
产生滚动方块。如果你传送一个图片，这意味着固定大小滚动方块与滚动条将不成比例。如果你尝试
产生一个滚动条对象，这可能会很适合。如果你传送三个，则第一个与第三个图片路径会指定顶层/
底部所使用的上下底。第二个图片是可拉长的中心。因此，三部分滚动条滚动方块始终是成比例的。
位移参数可以控制滚动方块应放置到距离滚动条多远的地方。例如，如果你指定 3， 滚动条图片
将会在滚动条视图左边缘的右侧显示出 3 个像素。针对水平滚动条，这是微调滚动方块的纵向数目。
请注意，目前水平滚动条图片必须以与垂直滚动条相同的方向建立。因此，需要水平设计 滚动条，
但是必须在切掉它们并节省出空间之前将它们顺时针旋转 90 度。
 
范例
myScrollbar.setThumbInfo( 1, new Array( "images/topCap.png",
"images/middle.png", "images/bottomCap.png" ) );
myScrollbar.setThumbInfo( 0, "images/fixedthumb.png" ) );
 
可用性
 
适用于 3.0 版或更高版本。
 

 
ScrollBar.setTrackInfo() 取代构成滚动条轨道的图片
语法定义
ScrollBar.setTrackInfo(int offset, int topLimit,
int bottomLimit, string|array images )
 
说明
虽然标准滚动条对象允许你自订色彩，但可能无法满足所有 Widget 的需要。要进行更多自订，
可以将一或三个图片路径传送给此函数 (分别做为字符串或数组)，轨道将使用那些图片来进行自我绘
制。如果你传送三个，第二个图片则是可拉长的中心。
位移参数可以控制轨道应放置到距离滚动条多远的地方 (或许你有一行长的像滚动条的轨道)。例
如，如果你指定 3， 图片将会从滚动条视图的左边缘显示 3 个像素。针对水平滚动条，这是微调轨
道图片的纵向数目。
topLimit 与 bottomLimit 参数可用来设定滚动方块滑动距离的限制。它们基本上都是「缓冲器」
限制。如果你想确定滚动方块无法从滚动条顶层小于 5 个像素的地方滑动，则请将 topLimit 指定为
5。
请注意，目前水平滚动条图片必须以与垂直滚动条相同的方向建立。因此，需要水平设计 滚动条，
但是必须在切掉它们并节省出空间之前将它们顺时针旋转 90 度。
 
范例
myScrollbar.setTrackInfo( 0, 2, 2, new Array( "images/topCap.png",
"images/middle.png", "images/bottomCap.png" ) );
 
可用性
适用于 3.0 版或更高版本。
 
 
ScrollBar.superview此视图的父视图
语法定义
frame|root ScrollBar.superview (read-only)
 
说明
此属性包含这个视图的父视图。父视图可以是「框体」对象或「根」对象。如果此视图没有父视
图，则此属性将会设定为空。
 
范例
var parent = myScrollBar.superview;
 
可用性
适用于 3.0 版或更高版本。必须至少将 Widget 的最低版本设定为 3.0 版才能使此属性存在。
 
 

Text 方法
Text.fade()淡入或淡出文字
 
语法定义
Text.fade(start, end, duration)
 
说明
fade() 命令将会使文字从开始透明度淡出到结束透明度。duration 可以指定要动画持续的时间
(十分之一秒)。
 
范例
newOpacity = 0;
myText.fade(myText.opacity, newOpacity, 6);
 
 
Text.moveTo() 通过动画将文字从点 a 移动到点 b
语法定义
Text.moveTo(newX, newY, duration)
 
说明
将文字的原点 (hOffset, vOffset) 移动到 newX 与 newY 所指定的新坐标。duration 可以指定
要动画持续的时间 (十分之一秒)。对象的移动是以动画的形式表现的 (这跟只改变 hOffset 与
vOffset 不同)。
 
范例
myText.moveTo(50, 50, 3);
 
Text.removeFromSuperview() 从其父视图中卸离文字
语法定义
Text.removeFromSuperview()
 
说明
使用此方法可将文字从窗口中移除。你可能会因为已经完成这个动作并重新加载了新信息而这样
做。卸离之后，如果你已经完成，就可以将其设定为空来只清除对它的应用，或如果你愿意的话，也
可以将它放入其它窗口或框体中。
当将 Widget 的最低版本设定为 3.0 版时，必须调用它以从窗口中移除对象。删除应用是没有用
的。

 
范例
myText.removeFromSuperview();
 
可用性
适用于 3.0 版或更高版本。
 
 
 
Text.slide() 以指定的方向与期间滑动文字
语法定义
Text.slide(direction, amountOfTextToConceal, duration)
 
说明
当要以特定方向滑动文字并使其消失在本身中而不仅仅只是移动时，便可使用 slide() 函数。
duration 可以指定要动画持续的时间 (十分之一秒)。
 
范例
myText.slide("up,left", 50, 8);
 
 
Text.superview此视图的父视图
语法定义
frame|root Text.superview (read-only)
 
说明
此属性包含这个视图的父视图。父视图可以是「框体」对象或「根」对象。如果此视图没有父视
图，则此属性将会设定为空。
 
范例
var parent = myText.superview;
 
可用性
适用于 3.0 版或更高版本。必须至少将 Widget 的最低版本设定为 3.0 版才能使此属性存在。
 
 
 

TextArea 方法
TextArea.focus()使目前 textarea 对象成为按下按键的焦点
语法定义
TextArea.focus()
 
说明
focus() 函数将使指定的 textarea 成为传送至按下按键的 textarea。当 Widget 有多个
textarea 且要将插入点从一个 textarea 移到另一个 textarea 时，这是非常有用的。textarea 必
须是 editable 的，这才会生效。
取得焦点之后，会针对 3.0 版或更高版本中的文字标签调用 onGainFocus 动作。
 
范例
mytextarea.focus();
 
 
TextArea.loseFocus() 如果文字标签目前是焦点则会释放键盘焦点
语法定义
TextArea.loseFocus()
 
说明
如果文字标签是目前的焦点 (通过调用 focus())，loseFocus() 函数会从文字标签中释放键盘焦
点。要在用户或许在做为搜寻字段使用的文字标签中输入数值之后清除焦点，此函数非常有用。当窗
口文字标签失去焦点时并不需要调用，因为在那种情况下它将会自动失去焦点。
失去焦点之后，会之对 3.0 版或更高版本中的文字标签调用 onLoseFocus 动作。
 
范例
mytextarea.loseFocus();
 
可用性
 
适用于 3.0 版或更高版本。
 
 
TextArea.rejectKeyPress() 控制 textarea 是否接受按键
语法定义
TextArea.rejectKeyPress()
 

说明
rejectKeyPress() 函数用于 <onKeyPress> 动作中以控制目前按下按键是否会影响 textarea。
 
范例
 <onKeyPress>
 <!-
//
将所有键入的字符变成大写
 var key = system.event.key;
 if (key.charCodeAt(0) >= "A".charCodeAt(0) &&
 key.charCodeAt(0) <= "z".charCodeAt(0))
{
 // 告知文字标签忽略掉这个按键
 // 因为我们要用我们自己的 ta1.rejectKeyPress();
 来取代它
 // 附加按下按键的大写副本
 // (插入点是一个长度为 0 的选择)
 ta1.replaceSelection(key.toUpperCase());
 }
// -->
</onKeyPress>
 
TextArea.removeFromSuperview()从父视图中卸离文字标签对象
语法定义
Image.removeFromSuperview()
 
说明
使用此方法可将文字标签对象从窗口中移除。你可能会因为已经完成这个动作并重新加载了新信
息而这样做。卸离之后，如果你已经完成，就可以将其设定为空来只清除对它的应用，或如果你愿意
的话，也可以将它放入其它窗口或框体中。
当将 Widget 的最低版本设定为 3.0 版时，必须调用它以从窗口中移除对象。删除应用是没有用
的。
 
范例
myTextArea.removeFromSuperview();
 
可用性
适用于 3.0 版或更高版本。
 
 
 
TextArea.replaceSelection() 用字符串来取代 textarea 中的目前选项
语法定义

TextArea.replaceSelection(string)
 
说明
replaceSelection() 函数可以使用指定的字符串来取代 textarea 中的目前选项。请注意，「游
标」或「插入点」实际上是零长度选项，因此，如果未在 textarea 中选择任何项目，则使用
replaceSelection() 将会具有在目前的光标位置插入指定字符串的效力。
 
范例
replacement = "new text";
mytextarea.replaceSelection(replacement);
 
TextArea.select() 选择 textarea 中的文字
语法定义
TextArea.select(start, end)
 
说明
选择功能可以改变文字标签中的选项。这将会选取从开始到结束的字符。特殊情况下，位置 –1 意
味着「文字结尾」，因此：
mytextarea.select(0, -1);
将会选择所有文字。
要设定「光标」或「插入点」的位置，请指定零长度选项，例如：
mytextarea.select(10, 10);
要在 textarea 中已有任何文字之后设定插入点，将使用：
mytextarea.select(-1, -1);
设定了插入点之后，将会滚动文字标签的内容以让用户可以看见它。
 
范例
mytextarea.select(5, 15);
 
 
 
TextArea.superview此视图的父视图
语法定义
frame|root TextArea.superview (read-only)
 
说明
此属性包含这个视图的父视图。父视图可以是「框体」对象或「根」对象。如果此视图没有父视
图，则此属性将会设定为空。
 
范例
var parent = myTextArea.superview;
 

可用性
适用于 3.0 版或更高版本。必须至少将 Widget 的最低版本设定为 3.0 版才能使此属性存在。
Timer 函数
 
Timer.reset() 重新开始定时器倒数
语法定义
Timer.reset()
 
说明
reset() 函数将会使计时器重新开始倒数。例如，如果你有一个以一分钟为间隔的定时器，且你
在它开始计时 30 秒之后调用 reset()，它将再次重新开始一分钟倒数。因此它将会重新开始并于一
分钟后触发，而不是在 30 秒后触发。
例如，当你尝试执行某种闲置定时器时，这是非常有用的。让我们假设一下，如果用户没有在 15
秒内与 Widget 互动，你便要在 Widget 中做一些事。如果用户点击 Widget，就可以启动将在 15 秒
后触发的定时器了。如果用户再点击，则你只可以重设定时器，重新开始 15 秒倒数。最后，如果 15
秒内没有发生点击的动作，便会触发定时器。
范例
myTimer.reset();
 
URL 对象
说明
URL 对象可以封装管理连接至远程资源所需的状态。URL 从未在 Widget 的 XML 部分中定义过。
方法
addPostFile()
为 POST请求新增文件。
cancel()
取消未完成的 fetchAsync 要求。
fetch()
在指定的 URL 上获取数据做为字符串。
fetchAsync()
在指定的 URL 上异步获取数据。
getResponseHeaders()
从 HTTP 回应中获取标头。
setRequestHeader()
设定 HTTP 请求的标头。
属性 (Attributes)
 
 
autoRedirect 设定是否自动重定向。
location 显示 URL 的字符串。
outputFile 如已设定，URL.fetch() 会以这个名称将获取的数据放入文件中。
postData 如已设定，URL.fetch() 将执行 POST 至指定位置，而非使用此字符串做为要

传送的数据的默认 GET。
response HTTP 回应程序代码指出了最新的 URL.fetch() 的结果。
responseData 实际响应数据，不考虑响应程序代码。
result 最新的 URL.fetch() 或 fetchAsync() 的结果。
范例
var url = new URL();
url.location = "http://www.yahoo.com";
contents = url.fetch();
 
URL.addPostFile() 添加提交的文件
语法定义
URL.addPostFile(path)
 
说明
 
此功能可将文件路径加入要与 POST 要求一起传送的文件清单中。实际传送 POST 之前并不会测
试此路径是否存在。加入文件之后， 要求会自动设为 POST 要求。
 
范例
var myURL = new URL;
myURL.addPostFile( "myfile.png", "/A/Local/File/Path.png" );
myURL.location = "http://mysite.com";
myURL.fetch();
 
可用性
适用于 2.1 版或更高版本。
 
 
URL.autoRedirect指出是否自动遵循重导
语法定义
URL.autoRedirect
 
说明
此属性可让你控制 URL 对象是否将自动遵循重导。默认值是 true。将此值设定为 false 将允许
你取得 302 重导响应并可按 想法来处理它。
 
范例
var myURL = new URL;
myURL.autoRedirect = false;
myURL.location = "http://mysite.com";
myURL.fetch();
 

可用性
适用于 2.1 版或更高版本。
 
URL.cancel()
取消通过 fetchAsync() 传送的异步要求
语法定义
 
URL.cancel()
说明
 
此函数可取消通过 fetchAsync() 传送的未完成要求。如果没有异步要求搁置便无效。如已调用，
则要求将会中断，且不会调用将正常接收要求结果的函数。
 
范例
myUrl.cancel();
 
可用性
适用于 2.1 版或更高版本。
 
范例
var myURL = new URL;
myURL.location = "http://mysite.com";
myURL.fetchAsync( myCallback );
...
myURL.cancel();
 
可用性
适用于 2.1 版或更高版本。
 
 
 
URL.clear() 清除 URL 对象的目前设定
语法定义
URL.clear()
 
说明
使用 URL 对象之后，如果要重复使用它来传送其它要求，可以调用 clear() 方法以确定之前传
送的任何数据 (文件等) 已不在对象中。如果你在目前正在执行异步要求的 URL 对象上调用此函数，
则会在清除对象之前取消要求。
 
范例
myURL = new URL;

myURL.location = "http://widgets.yahoo.com/"
result = myURL.fetch();
// reuse the object
myURL.clear();
myURL.location = "http://www.yahoo.com/"
result = myURL.fetch();
 
可用性
适用于 2.1 版或更高版本。
 
 
 
URL.fetch()返回 URL 数据做为字符串
语法定义
URL.fetch([location])
 
说明
从指定的远程位置或从在 URL 的 location 属性中指定的网页地址中获取数据。如果指定了位
置，这也会设定 URL 的 location 属性的数值。如果已设定了 outputFile 属性，则可将数据返回做
为字符串 (默认值) 或返回至文件中。因为这是同步完成的，所以 Widget 将会暂停，直到获取到资
源为止。
如果发生了错误且 fetch() 返回了一个字符串，那么它将返回字符串 "Could not load URL" (或
如果设定了属性 postData，则会返回字符串 "Could not load URL with POST" )。response 属性将
包含指出错误类型的程序代码。
注意：如果你正在获取 RSS feed (或任何网页资源)，请不要时常获取它。如要在 30 分钟之内
再次获取，请审慎考虑。 Widget 可能有数千人使用，且提供数据的网站可能并不喜欢自动转址的流
量。你还要确定你并没有内建一个配置方式，导致 Widget 的所有实例同时间尝试及获取数据 (例如，
准时每小时一次)，因为这也可能会使网站发生问题
(使用 onTimer 动作就可以了，因为不同人的 Widget 将在不同的时间启动)。
 
范例
var url = new URL();
webAddress = "http://www.yahoo.com";
contents = url.fetch(webAddress);
 
注意事项
在 2.1 版或更高版本中，也可以通过结果属性来取得结果。
 
 
 
URL.fetchAsync() 异步 GET 或 POST
语法定义

 
URL.fetchAsync(function)
 
说明
除了异步执行要求以外，它的运作方式与 fetch() 相似，可让 Widget 在要求完成的同时进行
其工作。要求完成后，它将调用你传送到函数中的函数。 函数接收启动要求的 url 对象，可以进行
查询以取得结果及/或要求的响应。
 
使用此函数将大大提高你 Widget 的响应能力，允许用户拖曳，同时在执行要求时与它进行互动。
 
范例
var url = new URL();
url.location = "http://www.yahoo.com";
url.fetchAsync(url_done);
function url_done( url )
{
print( "fetch complete" );
print( "response: " + url.response );
print( "result: " + url.result );
}
 
可用性
 
适用于 2.1 版或更高版本。
 
 
 
URL.getResponseHeaders() 从 HTTP 回应中返回标头
语法定义
URL.getResponseHeaders( name )
 
说明
此函数可让你取得伴随 HTTP 回应的标头。它最大的用途是取得 "Set-Cookie" 标头以供稍后使
用。基于安全的理由，2.1 版与更高版本会停用自动 cookie 处理，因此如果 Widget 需要使用 cookie
才能执行，将需要使用此函数以从响应中将它们取出。然后可以使用 setRequestHeader 来设定它们，
以将 cookie 返回稍后调用 fetch() 的服务器中。
此函数可返回与你传入的名称相符的标头数组。在 3.0 版或更高版本中，可以传送 "*" 做为名
称，然后将会收到完整标头的数组，包含名称 (传送名称将只会产生标头的数值)。
 
范例
var url = new URL();
url.location = "http://www.my_site.com";|
url.fetch();
var cookies = URL.getResponseHeaders( "Set-Cookie" );

 
可用性
适用于 2.1 版或更高版本。
 
 
URL.location URL 的网址
语法定义
URL.location
 
说明
指定 URL 将要从中获取数据的网址。
 
范例
var url = new URL();
url.location = "http://www.yahoo.com";
contents = url.fetch();
 
 
 
URL.outputFile指定存放数据的文件
语法定义
URL.outputFile
 
说明
指定要在其中存放获取数据的选用文件。如果你正在获取文字数据 (例如 HTML 文件)，通常只使
用 URL. fetch() 的返回数值会更容易一些，但是如果你正在获取二进制数据 (例如图片文件)，则必
须将获取的数据存放在文件中，因为将其转换为字符串的过程会将其转译为无效。
 
范例
var url = new URL();
url.outputFile = system.widgetDataFolder + "/mytempfile";
url.location = "http://www.example.com/graphic.jpg";
url.fetch();
myIng.src = url.outputFile;
 
 
URL.postData 提交给服务器的数据
语法定义
URL.postData

 
说明
设定 postData 会将 URL 对象 POST 到其位置，而非执行 GET 作业。如果不传送任何项目，请
将 postData 设定为空白字符串。要再次 GET URL 对象，请将 postData 设定为 null。
此数据的格式应以 url 编码，即每个参数都会以 name=value 传送，且参数会以 '&' 符号分隔。
当 数据包含空格、'&'、'=' 或非 ASCII 字符时，请使用 encode()。
 
范例
var url = new URL();
var text = encode( "a lot of &&& bad text" );
url.postData = "x=123&y=456&q=" + text;
contents = url.fetch("http://www.example.com/myscript.php");
 
 
URL.response HTTP 回应码
语法定义
URL.response
 
说明
response 属性指出了做为最后 fetch 调用接收的 HTTP 响应码。大于或等于 400 的响应码表示
完成要求时出现问题。
请注意，响应码只有在实际联络与作出要求的是网页服务器时才有用。如果服务器无法使用或为
location 提供了无效的 URL，则 response 属性将为 0 (零)。网页获取成功通常由响应码 200 表示。
依默认，Widget Engine 会进行自动重导，因此将不会看到响应码 302，除非将 autoRedirect 属性
设定为 false。
 
范例
var url = new URL();
url.location = "http://www.yahoo.com";
contents = url.fetch();
log("Response was: " + url.response);
 
 
 
URL.responseData
语法定义
URL.responseData
 
说明
无论返回的状态码为何，responseData 属性皆可用来从服务器中取得实际响应。这与 URL.result
属性不同，在这里，你始终可以取回真实的响应文字且绝不会取得任何状态字符串。如果连接失败，
则这个属性为空。

如果你从服务器取得 404 错误，则可以使用这个属性取得返回的 404 网页。
 
语法定义
var url = new URL();
url.location = "http://www.mysite.com/a_url_that_doesnt_exist";
url.fetch();
// 将会输出「无法加载 URL」
print( url.result );
// 将会输出服务器的实际回应
print( url.responseData );
 
可用性
适用于 2.1.1 版或更高版本。
 
URL.result上次获取的结果或错误字符串
语法定义
URL.result
 
说明
result 属性可以指出通过 fetch() 或 fetchAsync() 从上次所做的要求中接收的结果。这将包
含结果的实际文字 (例如网页)，或错误字符串「无法加载 URL」或「无法以 POST 加载 URL」。如果
即使当服务器的状态码不是 200 时你仍需要实际响应，请在 2.1.1 版或更高版本中使用
responseData。
 
范例
var url = new URL();
url.location = "http://www.yahoo.com";
url.fetch();
print( url.result );
 
可用性
适用于 2.1 版或更高版本。
 
 
URL.setRequestHeader() 在 HTTP 请求上设定标头
语法定义
URL.setRequestHeader( name, value )
 
说明
此函数可用来将标头设定为伴随 HTTP 要求。它最常见的用法是为要求设定 cookie。2.1 版会停
用自动 cookie 支持，因此必须要有这个函数才能继续使用 cookie。使用 getResponseHeaders 函数，
这个函数可以用来处理你 Widget 中的 cookie。在之前的响应中接收 cookie 后 (请参见

getResponseHeaders)，可以使用这个函数来在未来的要求中设定一或多个 cookie。名称参数是标头
的名称，该数值是标头的实际内容。
 
范例
var url = new URL();
url.location = "http://www.my_site.com";
url.setRequestHeader( "Cookie", myCookie );
url.fetch();
 
可用性
适用于 2.1 版或更高版本。
 
 
Widget 属性与函数
Widget.extractFile() 将 Widget 外的文件复制到 Widget 的数据文件夹中
语法定义
path = Widget.extractFile( file )
 
说明
此函数可以让将 Widget 外的文件复制到 Widget 的 'widget data' 文件夹中。3.1 版或更高版
本中的 flat-file Widget 尤其需要此函数，以便在文件系统中使用必须做为文件存在的项目 (例如
dll)。 Widget 不需要成为 flat-file Widget 便可使用此函数。
你可指定要获取的文件的相对路径，然后将会返回获取文件的路径。此函数可从全局 widget 对
象中存取。
 
范例
 var extPath = widget.extractFile( "Resources/myLibrary.dll" );
 
可用性
适用于 3.1 版或更高版本。
 
 
 
Widget.getLocalizedString() 返回指定按键的多语化字符串
语法定义
localString = Widget.getLocalizedString( key )
 
说明

此函数可以让你取得指定按键的多语化字符串。可以使用全局 widget 对象来调用此函数。
 
范例
var welcome = widget.getLocalizedString( "welcome_msg" );
 
可用性
适用于 3.1 版或更高版本。
 
 
 
Widget.locale 目前执行的语言/地区设置
语法定义
locale = Widget.locale (read-only)
 
说明
可以使用此属性来帮助你判断 Widget 现在在什么语言与地区之下执行。返回字符串的格式如下
所示：
<language>[_<locale>]
其中语言是小写 ISO 语言码，地区是大写 ISO 地区码。例如：
en
en_US
ja
地区部分是否在此将依据语言而定。例如，可能会有多种不同的英文 (美国、英国等)。如果你愿
意，可以使用此信息，或者如果要根据单独以语言为基础的简报来做任何决定，你只须看一下最前面
的两个字符即可。可以通过全局 widget 对象来存取此属性。
 
范例
var locale = widget.locale;
if ( locale.substr( 0, 2 ) == "en" )
print( "It's English" );
可用性
适用于 3.1 版或更高版本。
Window 属性与函数
 
Window.focus() 让窗口获得焦点
语法定义
Window.focus()
 
说明
如果因为某种原因，需要将窗口上移一层，可以在窗口上使用 focus() 方法。在 Windows 上，
这个 API 可能有时会无法将窗口完全上移，特别是当 Widget 未处于开始作用中的状态下。但是如果

你正与 Widget 互动且需要将检查器或其它次要窗口上移，这个 API 正好能够完成这个工作。
 
范例
myWindow.focus();
 
可用性
适用于 3.0 版或更高版本。
 
 
 
Window.locked 禁止用户拖曳窗口的能力
语法定义
Window.locked
 
说明
可以设定或检查窗口的锁定属性来控制用户是否可以拖曳窗口。这个设定值主要是由偏好对话框
中的 Widget「窗口」偏好设置控制。这个属性并未以 XML 接口表示。
 
范例
myWindow.locked = true;
 
 
 
Window.moveTo() 在屏幕上移动窗口
语法定义
Window.moveTo(newX, newY, duration)
 
说明
将窗口的原点 (hOffset, vOffset) 移动到由 newX 与 newY 指定的新坐标。duration 可以指定
要动画持续的时间 (十分之一秒)。对象的移动是以动画的形式表现的 (这跟只改变 hOffset 与
vOffset 不同)。
 
范例
myWindow.moveTo(150, 150, 2);
 
 
 
Window.recalcShadow() 重新计算 Widget 阴影
语法定义

Window.recalcShadow()
 
说明
如果拥有阴影的 Widget 改变了其形状 (例如通过隐藏或显示图片)，它将在将控制权交还给用户
之前调用其主窗口的 recalcShadow() 方法，以使阴影能够正确显示。如果 Widget 的窗口改变了大
小，则不需要调用此函数，因为阴影将会自动产生。
我们始终不能重新计算阴影的原因其实都是性能上的问题。
 
范例
if (myWindow.shadow)
myWindow.recalcShadow();
Windows 注意事项
3.1 版或更高版本在 Windows 上支持窗口阴影。
 
 
 
Window.root 窗口的根视图
语法定义
Root Window.root (read-only)
 
说明
此属性包含窗口的根视图。这个数值将永远不为空，且包含窗口最上层的所有视图。要将视图加
到窗口中，可以调用 root.addSubView() 或设定对象的 window 属性。在这两种情况下，视图都将为
根视图的子视图。
 
范例
var root = myWindow.root;
可用性
适用于 3.0 版或更高版本。必须至少将 Widget 的最低版本设定为 3.0 版才能使此属性存在。
 
 
Animation 对象
制作动画的辅助对象与函数
Widget Engine 的 2.1 版与更高版本都包含了可让你制作异步及同步动画的支持。它也可以让你
制作以 JavaScript 编写的自订动画。可以同时淡入/出或旋转所有对象。
一种被称为 animator 的新对象可以控制动画。可以告诉 animator 何时开始动画并异步执行它，
同时可让 Widget 做其它的事情。也可以取得一个动画 (或多个动画) 并同步执行它们，这意味着调
用将会遭到封锁，直到完成所有动画为止。
这些工具承担了制作精美动画的所有困难工作。它的 'ease'（渐入/渐出） 函数提供了简单的动
画技术，可在动画开始或结束时加快或放慢速度以取得更真实的动作效果。

每种动画类型都可以调用 'done' 回掉函数以使你得知动画何时完成。这个函数只有在异步执行
动画时才能调用。可以使用这个 done 函数来将动画链接在一起，在旧动画结束时开始新动画。
MoveAnimation’、FadeAnimation 与 RotateAnimation 对象都包含名为 owner 的对象，它是动
画操作所在的对象。通常需要确保对象在动画执行时没有取得回收的垃圾，但是可以使用此属性来应
用目标对象。
 
 
 
animator 主动画对象
在 2.1 版或更高版本中，animator 对象是动画系统的核心。
 
animator.ease()
在两个数字之间夹杂一个数字构成 'ease' 效果的表达式
 
语法定义
animator.ease( start, end, percent, easeType )
 
说明
此函数可用来帮你在动画中建立 'ease' 效果。所有 Widget Engine 2.0 版与更高版本中已有的
内置动画都有这种效果。实际上，可以使对象在离开时加速或在停止时减速，以赋予它更真实的移动
效果。
 
要使用这个函数，请将开始与结束数字与完成百分比以小数形式来传送 (例如，如果你完成一半，
则返回 0.5)。简单的类型是由其中一个附加在 animator 对象上的常数所指定的：kEaseNone、
kEaseIn、kEaseOut、kEaseInOut。请参阅这些常数的解释来了解它们的意义。
范例
var n = animator.ease( 0. 100, .7, animator.kEaseOut );
// 此时，根据 ease out 曲线，
// n 在 0 与 100 之间。它不是线性的。
可用性
适用于 2.1 版或更高版本。
 
animator.kEaseX
animator.kEaseIn
animator.kEaseOut
animator.kEaseInOut
animator.kEaseNone
表示要使用的渐入/出类型的常数
 

说明
这些常数会在建立不同动画对象与使用 animator.ease() 函数时使用。如果你熟悉渐入/出，则
引擎目前所使用的就是正弦曲线 ease 函数。
 
Ease In 是指对象将开始缓慢移动，然后在移动中加速。
Ease Out 是指对象将快速开始移动并在快要停止的时候减速。
Ease In/Out 是指对象将开始缓慢移动，然后达到最快速度，最后在接近终点时开始减速。
Ease None 是指没有有效的渐入/出。从开始到结束速度都不变。
可用性
适用于 2.1 版或更高版本。
 
animator.milliseconds目前的动画时间基础
说明
针对自订动画，取得目前的动画时间基础来标记开始时间 (或是只知道何时是「现在」) 是很有
用的。animator 的这个属性可以让你确定目前的时间。
 
范例
myAnimation.startTime = animator.milliseconds;
 
可用性
适用于 2.1 版或更高版本。
 
 
animator.runUntilDone() 执行一或多个动画直到结束为止
语法定义
animator.runUntilDone( object | array )
 
说明
这个函数可以用来执行一或多个动画，直到它们全部完成为止。在所有指定的动画完成之前，这
个函数都不会返回。因此，只有当你执行短的、有限的动画时，才应使用这个函数。例如「脉冲按钮」
效果之类的无限动画意味着这个调用将永远不会结束，因此请务必小心确定不会发生这种情况。
 
范例
// 交叉淡入/出
var a = new FadeAnimation( myImage1, 0, 350,
animator.kEaseOut );
var b = new FadeAnimation( myImage2, 255, 350,
 animator.kEaseOut );

animator.runUntilDone( new Array( a, b ) );
// 此时两个动画都已完成。
 
可用性
 
适用于 2.1 版或更高版本。
animator.start()
开始一或多个异步动画
 
语法定义
 
animator.start( object | array )
说明
这个函数可用来异步执行一或多个动画。这个函数会立即返回 — 它不会等待动画完成。实际上
动画甚至会在你结束 JavaScript 程序代码，且将控制权交还到 Widget 的主事件循环之后才开始。
这就是说，可以开始多个动画，而实际上它们将会同时开始。可以针对每个动画来调用开始，或将它
们做为数组全部传送到开始，这都没有关系。
 
范例
// 异步交叉淡入/出
var a = new FadeAnimation( myImage1, 0, 350,
animator.kEaseOut );
var b = new FadeAnimation( myImage2, 255, 350,
animator.kEaseOut );
animator.start( new Array( a, b ) );
 // 此时，一切都还未开始。当我们结束 Javascript 程序
码后，动画将会同时启动。
 
可用性
适用于 2.1 版或更高版本。
 
 
animation.kill() 终止执行动画的基本类别方法
语法定义
animation.kill()
 
说明
 
这个函数基本上是以下所有动画对象的「基本类别」函数。也就是说，它可以在以下任何动画对
象上调用。它可以用来停止可能正在执行中的异步动画。例如，如果在某种模式下，你有一个永不停
止旋转对象的动画，则当你结束此模式时，必须停止该动画。使用此函数就可以达到这个目的。
 

范例
 
var a = new CustomAnimation( 1, SpinMeRightRoundBaby );
animator.start( a );
// 一段时间之后，或许是在用户点击按钮之后
if ( a != undefined )
a.kill();
 
可用性
适用于 2.1 版或更高版本。
 
 
CustomAnimation() 以 JavaScript 编写的自订动画例程
语法定义
new CustomAnimation( interval, updateFunc [,doneFunc] );
 
说明
这是可以使用的最具有灵活性性的动画对象，但是你必须做所有的工作。一般来说，仅仅使用以
下提供的淡入/出、移动与旋转动画对象组合，便可做出一些非常有趣的事情。
第一个参数是动画应开始执行的间隔 (毫秒)。可以在更新函数中改变这个间隔。这可以让有可改
变速度等的动画。例如，沿着动画 GIF 的线条，其中每个框体都可拥有它自己的时间间隔。当调用 更
新函数时，'this' 对象就是动画本身，因此可以通过如下方式来改变间隔：
function MyUpdate()
{
this.interval = 5000; // switch to 5 seconds
return true;
}
下一个参数是 更新函数。这是你制作动画的地方。可以移动对象、改变它的透明度或做些真正有
趣的事情，例如调整图片的 HSL 设定值。在 update 函数返回 false 之后，才会执行自订动画。因
此，永久动画将始终返回 true，如上述程序代码片段一样。可以通过在动画上调用 kill() 的方法来
终止永久动画：
 
FadeAnimation() 调整对象透明度的动画对象
语法定义
new FadeAnimation( object, toOpacity, duration, easeType [, doneFunc]);
 
说明
这个动画对象可用来调整图片、框体、文字、文字标签或窗口对象的透明度。这可以用来淡入或
淡出对象。可以将你最终要达到的透明度传送到 toOpacity 参数中。期间单位为毫秒。可以在
easeType 参数中指定渐入/出的类型。
 
建立这个动画对象之后，可以将它传送到 animator.start() 或 animator.runUntilDone() 中。

如果通过 doneFunc 参数指定回掉函数，且以 animator.start() 来开始 动画，则当动画完成时，
将会调用你传送的函数。
 
范例
var a = new FadeAnimation( myObject, 0, 350,animator.kEaseOut, FadeDone );
animator.start( a );
 
function FadeDone()
{
 // 上述渐入/出已完成
print( "fade complete" );
}
 
可用性
 
适用于 2.1 版或更高版本。
 
 
MoveAnimation() 调整对象位置的动画对象
语法定义
new MoveAnimation( object, toX, toY, duration, easeType [, doneFunc]);
 
说明
这个动画对象可以用来调整图片、框体、文字、文字标签或窗口对象的位置。这可以用来在屏幕
上移动对象。它是通过调整你传入对象的 hOffset 与 vOffset 属性来产生作用的。可以传送你最终
要对象成为的 hOffset 与 vOffset。期间单位为毫秒。可以在 easeType 参数中指定渐入/出的类型。
建立这个动画对象之后，可以将它传送到 animator.start() 或 animator.runUntilDone() 中。
如果通过 doneFunc 参数指定回掉函数，且以 animator.start() 来开始动画，则当动画完成时，
将会调用你传送的函数。
 
范例
var a = new MoveAnimation( myObject, 100, 100, 350,animator.kEaseOut, MoveDone );
animator.start( a );
 
function MoveDone()
{
 // 上述移动已完成
print( "move complete" );
}
 
可用性
适用于 2.1 版或更高版本。
 
 

RotateAnimation() 调整对象旋转的动画对象
语法定义
new RotateAnimation( image, toAngle, duration, easeType [, doneFunc]);
 
说明
这个动画对象可以用来调整图片对象的旋转。它不会影响文字、文字标签或窗口对象。它通过调
整你传入图片的旋转属性来产生作用。期间单位为毫秒。可以在 easeType 参数中指定渐入/出的类型。
建立这个动画对象之后，可以将它传送到 animator.start() 或 animator.runUntilDone() 中。
如果你指定 doneFunc 为回掉函数，且以 animator.start() 来开始动画，则当动画完成时，将
会调用你指定的函数。
 
范例
var a = new RotateAnimation( myObject, 180, 350,animator.kEaseOut, RotateDone );
animator.start( a );
 
function RotateDone()
{
 // 上述旋转已完成
print( "rotate complete" );
}
 
可用性
适用于 2.1 版或更高版本
 
 
XML 服务 (XML Services)
关于XML 服务
Widget Engine 提供了多个处理 XML 的机制。使用这些服务，可以建立、分析及操纵 XML 树形
结构。你也可使用 XMLHttpRequest 的内置内建，即一种虚拟的标准来从网页服务器中获取 XML。
XML 文件的分析及建立是通过全局 XML 对象完成的。可以从中使用标准 W3C Level 1 DOM API 来
操纵 XML 树形结构。为使它更容易获取树形结构中的数据，我们通过增加 node.evaluate() 为你提
供了 XPath 1.0 内建。
 
DOM API
本节列出了目前受 Widget Engine 的 Level 1 W3C DOM 支持的各种对象与方法/属性。我们目前
提供完整 API 的子集。目前的分析程序还无法处理 DTD，因此它将无法做到例如使用默认数值自动填
写属性等类似的事情。
 
以下是我们所支持的属性与函数的简单概要。关于更进一步信息，建议你光临 w3c.org 网站。

DOMException
DOM 的标准异常类别。
当发生异常情况时，DOMException 会做为 Javascript 异常出现。可以检查对象的 code 属性来
查看发生的情形。Level 1 异常码为：
INDEX_SIZE_ERR 1
DOMSTRING_SIZE_ERR 2
HIERARCHY_REQUEST_ERR 3
WRONG_DOCUMENT_ERR 4
INVALID_CHARACTER_ERR 5
NO_DATA_ALLOWED_ERR 6
NO_MODIFICATION_ALLOWED_ERR 7
NOT_FOUND_ERR 8
NOT_SUPPORTED_ERR 9
IN_USE_ATTRIBUTE_ERR 10
 
DOMDocument
代表整个 XML 文件
 
属性
doctype
文件类型定义。
documentElement
文件的根元素。
函数
 
 
DOMElement createElement(string tagName);
针对文件以指定的标签名称建立新的元素节点。必须适当地使用 appendChild 来将它附加到文件
中。
DOMText createTextNode(string data);
针对文件以指定的内容建立新的文字节点。
DOMComment createComment(string data);
以指定的内容建立新的批注节点。
DOMCDATASection createCDATASection(string data);
以指定的数据建立新的 CDATA 区段。
DOMProcessingInstruction
createProcessingInstruction(string target, string data);
以指定的目标与数据建立新的处理指令。
DOMAttribute createAttribute(string name);
以指定的名称建立新的属性节点。
DOMNodeList getElementsByName(string name);
以指定的名称返回文件中所有元素的清单。
DOMNode importNode(DOMNode node, boolean deep);
将节点从其它一些文件中汇入到此文件中。适用于 3.1 版或更高版本。

DOMNode
XML 树中所有项目的基底类别
 
DOMNode
DOM API 中所有对象的基本类别。在日常生活中，你永远不会遇到 DOMNode，但是它的接口对所
有节点类型 (文字、元素、CDATA 等) 来说是很常见的，因此我们只会在这里介绍一次，而不会在每
遇到一个子类别时就再讲一次
 
属性
nodeName
此节点的名称。
nodeType
节点类型，以整数表示。
parentNode
此节点的父节点 (可以为空)。
childNodes
子节点的 DOMNodeList。
firstChild
此节点的第一个子节点。
lastChild
此节点的最后一个子节点。
previousSibling
目前节点的上一个同层级节点。
nextSibling
目前节点的下一个同层级节点。
attributes
此节点属性的 DOMNamedNodeMap (仅对「元素」节点有效，否则为空)。
ownerDocument
此节点所属的 DOMDocument。
 
函数
DOMNode insertBefore(DOMNode newChild, DOMNode refChild);
在此节点的子节点中的 refChild 之前插入 newChild。
DOMNode replaceChild(DOMNode newChild, DOMNode oldChild);
用 newChild 取代 oldChild。
DOMNode removeChild(DOMNode oldChild);
从此节点的子节点中移除 oldChild 并将它返回。
DOMNode appendChild(DOMNode newChild);
新增指定的子节点 (如果此节点类型允许子节点)。
boolean hasChildNodes();
如果此节点有子节点则返回 true。
DOMNode cloneNode(boolean deep);
复制此节点。如果 deep 为 true，则也复制所有衍生项目。
<various> evaluate(string xpath-expression);

这是由 Widget Engine 所定义的延伸，可让你在与引擎的 Xpath 支持之间建立接口。使用目前
的节点做为 XPath 表达式的内容，可以执行你所能想象得到的几乎任何 XPath 1.0 表达式 (某些特
定命名空间的函数除外)。结果可为字符串、数字或节点集。Widget Engine 会将节点集返回为
DOMNodeLists。关于更进一步信息，请参见有关 XPath 的小节。
string toXML();
Widget Engine DOMNode 延伸。将在此节点开始的子树形结构转换为 XML 以为写入到文件或可能
调试的目的而输出。
 
 
 
DOMNodeList 简单的节点清单
为了维持 W3C 的方式，任何通过 DOM API 表示的节点清单都是以 DOMNodeList 而非以
Javascript 数组的形式表示的。
 
属性
length
清单中项目的数目。
 
函数
DOMNode item(n)
返回清单中的第 n 个项目。DOMNodeLists 以零为基础。
 
 
 
DOMNamedNodeMap
依名称或索引存取的节点对映
当通过 DOMElement 节点的属性内容返回属性节点后，它们会以具名节点对映返回。此对映主要
是依名称存取的，但是你也可通过例如 DOMNodeList 的索引来回传送它。属性顺序没有保证，请勿以
它为准。
 
属性
length
清单中项目的数目。
 
函数
DOMNode getNamedItem(string name);
返回具有指定名称的项目，如果找不到该项目则返回空。
DOMNode setNamedItem(string node);
将指定的节点加到对映中。如果存在具有指定名称的节点，则取代它并返回旧节点。如果不存在
具有指定名称的节点，则返回空。
DOMNode removeNamedItem(string name);
如果存在具有指定名称的项目，则将它移除。

DOMNode item(int n);
返回清单中的第 n 个项目。DOMNodeLists 以零为基础。
 
 
DOMCharacterData
文字与批注节点的基本类别
不会在现实生活中遇到例如 DOMNode 的这种类别，但是它的接口可供 DOMText 与 DOMComment 节
点使用。对于 DOMNode 而言，接口只在这里显示一次，且不会在那两种类型中复制。
 
属性
data
实际字符数据。
length
字符数据的长度。
 
函数
string substringData(int offset, int count);
返回数据的子字符串做为字符串。它会返回以 offset 开始的数据的 count 字符。
 
void appendData(string data);
将指定的文字附加到节点的数据中。
 
void insertData(int offset, string data);
在指定的位移上插入指定的字符串。
 
void deleteData(int offset, int count);
删除以 offset 开始的数据的 count 字符。
 
void replaceData(int offset, int count, string data);
用 string 取代以 offset 开始的 count 字符的顺序。
 
 
 
DOMAttribute 元素的属性节点
属性
name
属性的名称。
value
属性的数值。在返回这个数值之前解析字符与实体应用。
 

DOMElement
元素节点
属性
tagName
元素的标签名称。
函数
 
string getAttribute(string name);
返回指定属性的数值，或如果该属性不存在，则返回空白字符串。
setAttribute(string name, string value);
将指定的属性与其数值加到元素中，取代可能已存在的相同名称的属性。
removeAttribute(string name);
如果存在，则移除具有指定名称的属性。
DOMAttribute getAttributeNode(string name);
返回与传入的名称对应的属性节点，或如果属性不存在，则返回空。
DOMAttribute setAttributeNode(DOMAttributes attr);
将指定的属性加到元素中，取代可能存在的具有相同名称的任何属性。如果此节点取代了现有节
点，则返回旧节点做为结果，否则返回空。
DOMAttribute removeAttributeNode(DOMAttribute attr);
将指定的节点从元素的属性中移除并返回它。
DOMNodeList getElementsByTagName(string name);
返回具有指定标签名称的所有元素清单，这些元素是此节点的衍生项目。
void normalize();
如果以目前元素开始的子树形结构中有邻近的 DOMText 节点，则这个函数可将它们合并为单一元
素。
 
 
 
DOMText 文字元素
函数
DOMText splitText(int offset);
将指定的节点分割为二，并新增新节点在树形结构中做为跟随其后的新同层级项目。此节点将包
含到 offset 为止的文字。以下节点将包含文字的剩余部分。返回新的文字节点。
DOMComment
批注节点
 
此节点仅拥有 DOMCharacterData 接口的属性与函数。
 
DOMCDATASection
CDATA 区段
此节点仅拥有 DOMCharacterData 接口的属性与函数。
DOMDocumentType
文件类型节点

目前，此节点仅定义名称属性。Widget Engine 的目前版本不支持实体与注释。
属性
name
文件根对象的名称。对于 Widget 而言，这将是 'widget'。对于 HTML 而言，它将是 'html'。
 
 
DOMNotation 注释节点
目前不受支持。
 
DOMEntity 实体的节点
目前不受支持。
 
 
DOMEntityReference 实体应用的节点
目前不受支持。
 
DOMProcessingInstruction
代表处理指令的节点
属性
target
处理指令的目标。
data
处理指令的内容。其范围从目标后的第一个非空格符到 "?>" 之前的字符。
 
 
XMLDOM 对象
XMLDOM 全局对象可让你分析及建立 XML 文件。请注意，如 Level 1 DOM API，你不可以通过新
增的方式来建立 DOMNode 实体。必须使用 XMLDOM 对象来建立文件，并使用文件本身来建立附加至文
件的元素 (例如，DOMDocument 是所有元素、文字项目、批注等的工厂)。
 
 

XMLDOM.createDocument() 建立新的空白 DOMDocument
 
语法定义
doc = XMLDOM.createDocument();
 
说明
这个函数可让你建立新 DOMDocument 元素。从那里，可以使用 DOMDocument API 来建立元素以
加到文件中，如在 W3C Level 1 DOM 规范中指定的一样。
 
范例
doc = XMLDOM.createDocument();
root = doc.createElement( "root" );
doc.appendChild( root );
print( doc.toXML() );
 
可用性
适用于 3.0 版或更高版本。
 
 
XMLDOM.parse() 分析 XML 及产生 DOMDocument
语法定义
doc = XMLDOM.parse(xml);
 
说明
分析函数可以分析指定的 XML 字符串 (可从网页服务器中取得，或使用例如
filesystem.readFile() 的调用) 并返回 DOMDocument 节点。文件节点是 W3C Level 1 DOMDocument
且符合 W3C 指定的 API (除去某些疏漏部分，例如实体对象)。
如果 xml 分析失败，则会出现包含错误字符串的异常。你始终应在 try/catch 标签内调用
XML.parse 以处理失败问题。
 
范例
try
{
 doc = XMLDOM.parse( xmlStream );
 root = doc.documentElement;
 ...
}
catch( e )
{
print( e );
}
可用性

适用于 3.0 版或更高版本。
 
XMLHttpRequest
说明
 
XMLHttpRequest 对象与 Widget Engine 中很早就已经存在的 URL 对象非常类似。但是，
XMLHttpRequest 是在网页浏览器中 http 上做 XML 的原厂默认标准，因此在这里增加它为人们将
AJAX 码移动到 Widget Engine 中以及仅尝试符合标准提供了更简易的转换路径
以使开发人员更容易找到它。
 
方法
abort()
取消未完成的异步要求。
getAllResponseHeaders()
返回所有响应标头。
getResponseHeader()
返回特定回应标头。
open()
设定我们的要求参数。
send()
传送含有选用数据的要求。
setRequestHeader()
为请求设定标头。
 
属性 (Attributes)
 
onReadyStateChange 将函数指定为要求改变的状态。
ReadyState onreadystatechange 函数中使用的要求的目前状态。
ResponseText 响应的文字 (例如网页或 XML 文字)。
ResponseXML 如果响应是文字/xml，则此属性将会包含代表已接收的 XML 的 DOMDocument。
Status HTTP 状态码 (例如 200)。
StatusText HTTP 状态字 (例如「确定」)。
 
范例
var req = new XMLHttpRequest();
req.open( "GET", "http://www.yahoo.com", false );
req.send();
print( req.responseText );
XMLHttpRequest.abort() 中止异步要求
语法定义
XMLHttpRequest.abort()

可用性
适用于 3.0 版或更高版本。
 
 
array XMLHttpRequest.getAllResponseHeaders()
 
说明
要求完成之后，这个调用可用来获取以做为字符串数组的响应返回的所有标头。
 
范例
var headers = request.getAllResponseHeaders();
 
可用性
适用于 3.0 版或更高版本。
 
 
 
XMLHttpRequest.getResponseHeader() 依名称返回来自响应的一或多个标头
语法定义
string|array XMLHttpRequest.getReponseHeader(string)
说明
 
要求完成之后，这个调用可用来获取拥有指定名称的一或多个标头。如果只有一个标头，它将会
返回单一字符串结果。如果有多个标头，它将会返回相符的数组。
 
范例
var cookies = request.getResponseHeader( "Set-Cookie" );
 
 
说明
如果针对 open() 的异步参数传送了 true，则此调用便可用来终止尚未完成的要求。
 
范例
request.abort();
 
可用性
适用于 3.0 版或更高版本。
 
 
XMLHttpRequest.getAllResponseHeaders() 返回来自响应的所有标头
语法定义

XMLHttpRequest.onreadystatechange 当处理异步要求时所调用的函数
语法定义
XMLHttpRequest.onreadystatechange
 
说明
如果是异步传送要求 (参见 open())，你则必须在改变要求的状态时指定要调用的函数。不会有
参数被传送给这个函数。当调用了 函数后，'this' 便应用了要求。通常，将只会关心要求的
readyState 何时为数值 4 (完成)。
 
范例
var request = new XMLHttpRequest();
request.onreadystatechange = myStatusProc;
request.open( "GET", "http://www.yahoo.com", true );
request.send();
// 其它地方
function myStatusProc()
{
 if ( this.readyState == 4 ) // 完成
{
print( this.status );
}
}
 
可用性
适用于 3.0 版或更高版本。
 
XMLHttpRequest.open() 设定传送的要求
语法定义
XMLHttpRequest.open(method,url,async);
 
说明
这设定了传送的要求。你传送了表示你是否要异步传送这个要求的方法、url 与旗标。请注意，
目前我们不支持传统的用户名称与密码参数。或许它会在稍后发行的版本中受到支持。
方法参数的有效数值有 "GET"、"POST"、"HEAD"、"OPTIONS"、"PUT" 与 "DELETE"。
 
范例
var request = new XMLHttpRequest();
request.onreadystatechange = myStatusProc;
request.open( "GET", "http://www.yahoo.com", true );
request.send();
 
可用性
适用于 3.0 版或更高版本。

 
 
XMLHttpRequest.readyState 要求的目前状态
语法定义
XMLHttpRequest.readyState (read-only)
 
说明
这可以用来判断要求的目前状态。一般情况下，这只有在 onreadystatechange 函数中传送异步
要求时才会使用。
 
readyState 的数值是：
 
0
未初始化
1
正在载入
2
已载入
3
互动
4
完成
 
Widget Engine 只会在 3.0 版本中将 readyState 设定为 0、1 或 4。
范例
var request = new XMLHttpRequest();
request.onreadystatechange = myStatusProc;
request.open( "GET", "http://www.yahoo.com", true );
request.send();
// 其它地方
function myStatusProc()
{
 if ( this.readyState == 4 ) // 完成
{
print( this.status );
}
}
 
可用性
适用于 3.0 版或更高版本。
 
 
 
XMLHttpRequest.responseText 返回的文字
语法定义
XMLHttpRequest.responseText (read-only)

 
说明
这个属性包含网页服务器针对你传送的要求返回的文字。一般情况下，这将会是网页或 XML。
 
范例
var request = new XMLHttpRequest();
request.open( "GET", "http://www.yahoo.com", false );
request.send();
if ( request.status == 200 )
 print( request.responseText );
 
可用性
适用于 3.0 版或更高版本。
 
XMLHttpRequest.responseXML 按要求返回的 XML DOM
语法定义
 
XMLHttpRequest.responseXML (read-only)
 
说明
如果对于要求的响应返回了 "text/xml" 内容类型的数据，则此属性将包含代表 XML 文件的
DOMDocument 节点 (例如，它将会自动分析并准备好供使用)。如果文件无法分析，或内容类型不是
"text/xml"，则此属性将会设定为空。
 
范例
var request = new XMLHttpRequest();
request.open( "GET", "http://www.yahoo.com", false );
request.send();
if ( request.status == 200 )
 print( request.responseXML.toXML() );
 
可用性
适用于 3.0 版或更高版本。
 
 
XMLHttpRequest.send() 将请求传送到服务器
语法定义
XMLHttpRequest.send([body])
 
说明
实际上这个函数确实将数据传送到了服务器。可以选择性地将做为 HTTP 要求主体传送的数据传
送到这个函数中。

 
范例
var request = new XMLHttpRequest();
request.open( "POST", "http://www.yahoo.com", false );
request.send( someXML );
 
可用性
适用于 3.0 版或更高版本。
 
 
 
XMLHttpRequest.setRequestHeader() 设定请求标头
语法定义
XMLHttpRequest.setRequestHeader(name,value)
 
说明
这个函数可将标头加到要求中，这可能会取代名称相同的现有标头。
 
范例
var request = new XMLHttpRequest();
request.open( "POST", "http://www.yahoo.com", false );
request.setRequestHeader( "Content-type", "text/xml" );
request.send( xml );
 
可用性
适用于 3.0 版或更高版本。
 
 
XMLHttpRequest.status 返回回应的状态
 
语法定义
XMLHttpRequest.status (read-only)
 
说明
此属性代表服务器返回的 HTTP 状态码，例如 200、404 等。
 
范例
var request = new XMLHttpRequest();
request.open( "POST", "http://www.yahoo.com", false );
request.setRequestHeader( "Content-type", "text/xml" );
request.send( xml );
if ( request.status == 200 ) // 成功！

DoSomethingWonderful();
 
可用性
适用于 3.0 版或更高版本。
 
XMLHttpRequest.statusText 响应的状态字
语法定义
XMLHttpRequest.statusText (read-only)
说明
此属性代表服务器返回的 HTTP 状态字，例如，「确定」、「找不到」等。它们与返回的代码相对应。
范例
var request = new XMLHttpRequest();
request.open( "POST", "http://www.yahoo.com", false );
request.setRequestHeader( "Content-type", "text/xml" );
request.send( xml );
if ( request.statusText == "OK" ) // 成功！
DoSomethingWonderful();
 
可用性
适用于 3.0 版或更高版本。
 
XPath Support
从 3.0 版开始，Widget Engine 支持从 XML 树形结构中获取节点与节点信息的 XPath 1.0 语言。
可能你几乎从未使用过原始 DOM API 来获取节点信息，而使用 Xpath，这更容易也更直接。本节说明
如何将它整合到 Widget Engine 中，以及存取它的方法，如何使用它的部分范例。
这只是简要说明，完整的信息请参阅 XPath 1.0 的 w3c.org 网站。
首先，我们来看一下 XML 层次结构范例：
<?xml version="1.0" encoding="utf-8"?>
<my-data>
<element1 name="fred" size="200">
这是一些文字
 </element1>
 <image-list>
<image size="32"
src="http://www.yahoo.com/image.png"/>
<image size="48"
src="http://www.yahoo.com/image2.png"/>
 </image-list>
</my-data>
现在让我们尝试做一些特定的事情。通常，XPath 会返回节点清单。Widget Engine 会将那些节
点做为 DOMNodeList 返回。XPath 于「内容节点」开始，即是与 XPath 搜寻相关的地方。也可以在

路径开头加个 '/' 来指定从顶层开始搜寻。假设在名为 doc 的变量中有文件节点：
element = doc.evaluate( "my-data/element1" );
上述范例获取了与路径 "my-data/element1" 相符的所有节点 (在这种情况下是一个节点) 且将
它做为节点清单返回。
images = doc.evaluate( "my-data/image-list/image" );
上述语句会返回所有与指定路径相符的节点。此时，我们将取回含有两个元素 (图片清单的两个
子节点) 的节点清单。
这是最简单的 XPath ―― 直接从文件中选择节点。现在讨论要更复杂一点的情况。假设要选择
大小为 48 的图片。可以针对此动作使用述词（谓语？），述词是套用到搜寻上的条件，它筛选出那些
与条件相符的结果。
image = doc.evaluate( "my-data/image-list/image[@size='48']" );
 
这就是说「寻找所有与此路径相符的项目，但只找出那些 'size' 属性数值为 48 的项目」。@ 符
号是表示正在寻找属性的简单写法。述词的正常写法为 [attribute::name='48']。
 
现在，如果要取得该图片的 src 属性，可以这样做：
src = image.item(0).getAttribute( src );
稍后将会看到更简单的方法。首先获取部分文字。假设我们要 element1 中的文字，有一种方法
可以达到这个目的：
element = doc.evaluate( "my-data/element1" );
text = element.item(0).firstChild.data;
需要了解元素是否真的是节点清单，因此我们获取了 item 0，然后向它询问它的第一个子件 (如
XML 树形结构所示，文字的确是 element1 的子节点)，然后我们取得它的数据。这个方法很有效，但
稍嫌复杂。幸运地是，XPath 的string() 函数可以让一切变得更加简单：
text = doc.evaluate( "string(my-data/element1)" );
string() 函数把传送给它的参数转换为字符串。针对元素节点，它会取出所有在它之下的文字子
元素，并串连它们后返回。在此例中，只有一个元素与一个文字节点，因此取得了我们要的精确结果。
针对属性节点，string() 会返回属性的数值。现在再试一次上述案例以取得大小为 48 的图片的 src
属性：
src = doc.evaluate( "string(my-data/image-list/image[@size='48']/
attribute::src)" );
这一次使用了与之前相同的路径，但是这次加入了其它路径区段以从结果中获取 src 属性，然后
字符串函数会返回该属性的数值。
使用 xpath 可以在 XML 中搜寻各种东西，且有许多搜寻方法。可以寻找含有某种父件的元素，
可以获取含有特殊子元素等的元素。关于更进一步信息，请参阅 w3c.org 网站上的完整 XPath 1.0 规
范。
 
 
 
 

附录：
Windows 与 Mac OS X 版 Widget 的差异
本节指出 Widget Engine 的 Mac 版本与 PC 版本的差异。
Unix 命令
首先，因为 PC 不是以 UNIX 为基础（而 Mac OS X 却是），所以不能保证已成功在 Mac 上使用
runCommand 的 Widget 在 Windows 上也能同样成功。为使尽可能多的 Widgets 可跨平台执行，针对
Windows 版本的 Widget Engine提供一些 Yahoo 随附命令：
basename
bc
bunzip2
bzip2
bzip2recover
cal
cat
cksum
cmp
Comm.
compress
cp
curl
cut
Date
dc
dd
df
diff3
Diff
dirname
du
echo
egrep
Env
expand
expr
fgrep
find
Fmt
fold
fsplit
gawk
grep
Gunzip
gzip
head
id
join
Less
lesskey
ln
logname
ls
m4
md5sum
mkdir
mv
od
Open
paste
patch
pr
printenv
Pwd
rm
rmdir
sdiff
sed
Shar
sleep
sort
split
sum
Sync
tail
tar
tee
touch
Tr
uname
unexpand
uniq
unzip
Uudecode
uuencode
wc
which
whoami
Xargs
yes
zcat
zip
 
 
 
此外，"sh" 也可用来执行shell 命令。
命令键
Windows 上并没有「命令」键。需要要使用它时，请使用「控制」键。因此，当你要拖曳 Widget
时，请按住「控制」键拖曳。
热键
当按下 Windows 键盘上的 Delete 键后，会收到 "ForwardDelete"消息，而按下 Backspace将
会收到 "Delete"消息。这是依照了 Mac 的按键命名，我们无法改变它。Return 及 Enter 也有一点

类似。大多数 (如果并非所有) Windows 键盘上都没有 Return 键，但一定会有 Enter 键。在 Mac 键
盘上这是两个完全不同的按键。按下 Windows 上的 enter 键，返回的是 "Return" 消息，目前这也
是无法改变的事情，因此请注意它。
 
如果在 Mac 上设定的热键是 cmd-control-<key>，那么在 Windows 上它将仅是 control-<key>
(因为没有「命令」键)。
在 Windows 上注册热键时，此键是专用的，这一点与 Mac 操作系统不同。因此，不同的 Widget 无
法注册相同的热键；第二个要注意的是 happy fun key，目前还没有任何方法可以让 Widget 知道这
一点。
 
通常，F1 是不应使用的，因为它是「说明」键；F12 在 2000/XP 与最新的 NT 各版本上保留给
调试程序使用。
 
按键的释放不产生任何通知，只要按键被按下， onKeyUp 句柄就永远不会在 Windows 上被触发
了。
某些热键顺序是非法的，如 alt-tab 与 ctrl-alt-delete。
路径
Mac OS X 的原始路径是 UNIX 式的，或正斜线路径。Windows 则有磁盘驱动器代号与倒斜线符
号。Widget Engine 的原始路径样式为正斜线路径。这是因为继承 Mac 与 JavaScript 风格的原因。
如果使用 runCommand 来调用 UNIX 或 Windows 函数，需要正确地转换路径。UNIX 命令可以接受正
斜线，也可以接受倒斜线路径，但是Windows 命令则必须使用倒斜线路径。要使两者之间实现相互转
换，应使用 convertPathToPlatform 函数。但是目前还没有从 Windows 样式转换为 UNIX/JavaScript
样式的函数。
convertPathToHFS 将会在 Windows 上返回空白字符串。
Perl 与 PHP
对于 Windows 而言，Widget Engine 并不支持 Perl 或 PHP，因此建议那些要求 Perl 的 Widget
将用户指向适当的 Perl PHP 环境。
 
封装工具
3.1 版引擎中推出了 Widget 的 flat-file 封装格式。为了产生 flat-file 封装格式，提供了
一套 'Converter' 命工具。此工具必须位于引擎可执行文件所在的目录中。
此工具将可将 Widget 在包格式与 flat 封装格式之间转换；可以在 Widget 中加入数字签名(证书)。
为了能够签名并通过完整性验证，必须拥有 Verisign 的 Netscape Code Signing 证书。其它的根证
书授权会在未来的版本中得到支持。如果 Widget使用其它类型的证书签名，完整性可得到确认，但
是引擎将无法验证签名的真实性 (将无法确定 身份)。当 Widget 第一次执行 (以及Widget 以某种
方式被修改了) 时，这种类型的信息将会显示给用户。
 

以下是封装工具的语法：
converter [-v] [-list] [-flat | -unflat] [-sign –key host.key –cert
 certfile [-p foo | -pf passfile]] [-verify] file-or-bundle
 [-o output-dir]
 
-list
列出 Widget 中封装的内容。
 
-flat
以flat格式封装 Widget。
 
-unflat
解开以flat格式封装的 Widget。
 
-sign [sign-params]
签名选项，在封装 Widget (如果平面已指定) 之后加入数字签名，或者签名已经封装过的 Widget。
 
 -verify
确认 Widget 的签名。
 
-cert
签名参数
 
要签名的证书文件 (.pem 格式)。
-key
 
签名使用的私钥 (.pem 格式)。
-p | -pf [filename]
可以使用 –p 在命令行上直接指定用于密码保护的私钥。如果要在文件中指定密码，可以使用 –pf，
这对于自动建立 Widget 的程序是非常有帮助的，不需要将密码置于来源控制中。
 
选项
-V
详细信息模式，完整打印工具版本与状态信息。
 
-o [output-dir]
指定放置转换/签名文件的目录。
 
 
 
OpenSSL 授权
本产品使用 OpenSSL进行数字签名/身份验证。
/* ===================================================================

 * 著作权 (c) 1998-2005 The OpenSSL Project。保留所有权利。
* 在符合以下条件的情况下，允许修改或未修改的原始代码与可执行文件的重新发布：
 
 * 1. 源代码的重新发布必须保留以上著作权注意事项、本条件清单以及以下免责声明。
*
* 2. 可执行文件的重新发布必须在发布所附的文件与/或其它材料中包含以上著作权注意事项、本条
件清单以及下面的免责声明。
*
* 3. 所有提到本软件的功能或使用方法的广告材料必须显示以下文字：
 * 「本产品内含由 OpenSSL Project 开发用于 OpenSSL Toolkit 中的软件
(http://www.openssl.org/)」
 *
 * 4. 未经书面许可，“OpenSSL Toolkit” 与 “OpenSSL Project” 之名称不可用来推销本软件。
关于书面许可的信息，请与 [e-mail] 联系。
 *
* 5. 未经 OpenSSL Project 的书面许可，由本软件衍生的产品不可称为 “OpenSSL”，也不得在它
们的名字中出现 “OpenSSL”。
*
* 6. 任何格式的重新发布都必须保留以下文字：
 * 「本产品包含由 OpenSSL Project 开发并用于 OpenSSL Toolkit 中的软件。
 * 本软件由 OpenSSL PROJECT提供，任何情况下，OpenSSL PROJECT 或其参与者不对任何直接的、
间接的、偶然的、特殊的、惩罚性的或必然性的损失负责 (包括但不限于替代品或服务的取得；使用
权、资料或利益的损失；业务的中断)。
 
SSLeay 授权
====================================================================
 *
 * 本产品包含 Eric Young ([e-mail]) 编写的密码编译软件以及 Tim Hudson
* ([e-mail]) 编写的 SSLeay 软件。
 *
 ----------------------
/* 著作权 (C) 1995-1998 Eric Young ([e-mail]) 保留所有权利。
 * 本封装由 Eric Young ([e-mail]) 编写，符合 Netscapes SSL 标准。
 *
* 只要符合以下条件，商业或非商业用途皆可免费使用本软件，这些条件适用于本内容中的所有程序
代码（包括 RC4、RSA、lhash、DES 等程序代码，不仅仅是 SSL）。附带的 SSL 文件受到相同的著作
权条款保护，所有者 Tim Hudson ([e-mail]) 不受限制。
 * 著作权属于 Eric Young ，程序代码中的任何著作权注意事项均不可移除。
 * 如果要在产品中使用本封装，应将 Eric Young 列为共同作者之一，这可以以文字信息形式出现在
封装随附的程序或文件 (在线或文字) 中。
 
* 符合以下条件时，允许修改或未修改版本的重新发布：
 * 1. 源代码的重新发布必须保留著作权注意事项、此条件清单和下面的免责声明。

 * 2. 可执行程序的重新发布必须在所附的文件与/或其它材料中包含以上著作权注意事项、本条件清
单以及以下免责声明。
 * 3. 所有提到此软件功能或使用方法的广告必须显示以下通知：
 * 「本产品包含 Eric Young ([e-mail]) 编写的密码编译软件。」 如果使用的链接库中
的例程与密码编译无关，则无须加上「密码编译」一词。:-)
 * 4. 如果包含了应用程序目录 (应用程序程序代码) 中的任何 Windows 特定程序代码 (或衍生产
品)，必须包含以下通知：
 * 「本产品包含由 Tim Hudson ([e-mail]) 编写的软件。」
 * 任何情况下，OpenSSL PROJECT 与其参与者不对任何直接的、间接的、偶然的、特殊的、惩罚性
的或必然性的损失负责 (使用权、资料或利益的损失；业务的中断)，无论任何原因以及任何理论上的
责任，是否在合约、严格责任或侵权行为中 (包括疏忽或其它情况) 在使用本软件以外的任何情况下
发生，即使已获此类损坏发生可能性之建议亦然。
 *
* 本法规的任何公开版本或衍生品的授权与发布条件不能改变，不能简单地复制并置于其它发布授权
之下 [包括 GNU 公共授权]。
*/