当前小工具对象集包括 4.0 版本之前的对象集中的一些对象。一些这样的对象（特别是 googleTalk 和 contentItem）采用与上述模型不同的事件处理模型。在下面的 API 参考中，这些对象列出了相关的事件句柄，而不仅仅是事件。
对于这些 4.0 版本之前的对象，要处理某一事件，需要为该特定事件设置句柄函数。这些句柄函数只能在 JavaScript 或 VBScript 块内进行设置，而不能像 4.0 版本的对象那样在 XML 定义中设置。
事件句柄为“只写”句柄，对于它们，您只能为其指定函数。如果您未设置特定句柄，则在响应相关事件时，会执行默认操作。在其 API 参考部分的说明中，我们为各个事件句柄指定了原型签名；您为特定事件句柄指定的函数应与其原型签名匹配。
我们看一下选项与菜单样例代码的相关部分，以了解事件句柄的具体使用方法。
// 设置的小工具属性，类似于“世界您好”示例。
// ...
// 在小工具对象的 onAddCustomMenuItems 事件与
// 脚本中定义的函数间建立关联。
plugin.onAddCustomMenuItems = AddCustomMenuItems; // 添加菜单项的句柄
// ...
function AddCustomMenuItems(menu) {
// 添加不同项目布局作为菜单项，并查看当前所选布局
var itemLayout = options.GetValue("item_layout");
for (var i = 0; i < menuItems.length; ++i) {
if (i == itemLayout) {
menu.AddItem(menuItems[i], gddMenuItemFlagChecked, MenuItemClicked);
} else {
menu.AddItem(menuItems[i], 0, MenuItemClicked);
}
}
}
// ...
在该例中，我们为 plugin 对象的 onAddCustomMenuItems 事件指定了 AddCustomMenuItems 函数。请注意，所指定的值仅包含函数名，并不完全包含参数签名。补充工具栏在显示小工具的菜单前需要对其进行初始化，此时即会发生该事件。
为 AddCustomMenuItems 列出的原型为 AddCustomMenuItems(menu)，因此，我们指定的函数也应仅带有一个参数，即 menu 对象。
对象概述
在本部分中，我们将了解各种对象，并着重研究这些对象的用途以及关系。
gadget 对象gadget 在整个小工具级有两种不同用途。
- 在以调试模式运行时，gadget.debug 可以在调试控制台中显示您所进行的一系列选择，从而可以帮助您进行调试。
要以调试模式运行，请解压缩您的小工具，并双击所获得的文件中的 gadget.gmanifest 文件。这样，开发您的小工具时，您就不必在每次想要测试时都要进行压缩。
仅当从文件夹中启动小工具（通过点击 gadget.gmanifest）时，调试控制台中才会显示调试消息。在通过 .gg 文件启动小工具时，不会显示调试信息。消息显示在设计器调试控制台或随 Google 桌面 SDK 提供的 gdpconsole.exe 中。
- gadget.storage 方法用于构成整个小工具包的文件。利用这些方法，您可以提取并打开包中的文件。该存储对象的文件名参数可以使用以下参数：
- “foo.xml”在 .gg 文件的根文件夹中查找 foo.xml。如果不能找到，则在本地化文件夹（例如 1033\foo.xml）中查找。
- “子文件夹\foo.xml”在 .gg 文件的子文件夹文件夹中查找 foo.xml。如果不能找到，则在本地化文件夹的子文件夹文件夹（例如 1033\subfolder\foo.xml）中查找。
- “c:\bar.xml”在 c:\ 驱动器中查找 bar.xml。请提供精确路径。
view 对象您应为小工具所拥有的各个整体窗格外观定义 view 对象。这些对象应分别采用单独的 .XML 文件。在您创建项目时，设计器会自动创建包含 view 对象的 main.xml 文件。同时，它还会创建包含自己的 view 属性的 options.xml 文件。
view 的属性和方法定义并使用视图窗格的全部行为。其中包括构成窗格外观的用户界面元素、窗格大小、用户是否可以调整大小、控制脚本执行的计时器、添加或删除用户界面元素以及消息/确认框的显示情况。
view 的事件会根据以下操作触发和运行函数：各种鼠标按钮操作、键盘操作、重新调整大小、属性值更改、光标操作以及第一次打开该视图。
basicElement 和用户界面对象basicElement 是构成特定视图视觉外观的各种用户界面元素的父对象。basicElement 本身从不实例化，而只是为其子用户界面对象提供一系列常用属性和事件。
属性指定了元素的大小和位置、名称、可见度与不透明度以及其他一般用户界面元素属性。
事件为与用户界面对象相关的常用事件；操作包括鼠标点击或滚轮、拖放元素、获得或失去键盘焦点、键盘操作、光标移动等。
您可以定义以下 basicElement 子元素：
- button：您可利用此类特定属性为按钮及其不同状态设置不同图片。
- checkbox：您可利用此类特定属性为复选框及其不同状态设置不同图片，还可利用它们确定框是否为选中状态。在框的选中值更改时，会触发事件。
- object：嵌入式无窗口 ActiveX 控件。主要用于 Windows Media Player 嵌入。
- div：用来设置元素背景颜色或图片。
- edit：您可利用此类特定属性控制其文本内容外观及设置或检索其文本内容。在内容更改时，会触发事件。
- img：您可利用此类特定属性设置要显示的图片并获取其原始尺寸。它同时包含了重新设置图片大小的方法。
- label：您可利用此类特定属性控制标签文字的外观及位置/排列方式。
- a：您可以利用这一链接对象的特定属性控制链接的外观及其网址。
- progressBar：此类特定属性控制进度条及其组件的外观以及值更改时触发的事件。
另外还有 elements 对象，该对象表示 basicElement 的子对象的容器。
options 对象将选项及其值存储为标准字典/映射。下面两种设置值的方法效果相同：
options("键") = "值";
options.item("键") = "值";
与所有目录类似，您可以通过两种方法之一添加项目：
options("键") = "值"; // 添加或替换当前值。
options.add("键", "值"); // 添加值，如该值已经存在，则不执行任何操作。
defaultValue 属性允许键在字典中没有与之相关的实际值时返回默认值，从而使您不必再检查该键是否存在值。例如：
options.defaultValue("color") = "red";
此时，只要请求“color”且字典中实际并不存在“color”，就会返回“red”。例如：
options.defaultValue("color") = "red";
options("color") = "blue";
debug.trace(options( "color")); // 显示“blue”
options.remove("color");
debug.trace(options("color")); // 显示“red”（默认值）
options("texture") = "bumpy";
debug.trace(options("texture")); // 显示“bumpy”
options.remove("texture");
debug.trace(options("texture")); // 显示“”（因为没有默认值）
4.0 版本之前的对象（googleTalk、friend、ContentItem、menu、DetailsView）4.0 开发模型中包含了 4.0 版本之前的开发模型中的四种对象：googleTalk、friend、ContentItem 和 menu。请记住，在代码中使用 googleTalk 或 menu 事件句柄时，需要使用 4.0 版本之前的事件处理模型。另外，与其他用户界面元素不同，这些元素并不是 basicElement 的子元素。
有关如何使用 googleTalk 和 friend 对象编写可与您的计算机上运行的小工具进行通信的小工具的详细信息，请参阅 Google 桌面补充工具栏通信 API 文档 (其他文档目前仅提供英语版本)。
利用 menu 对象及其方法，您可以为小工具构造多项菜单，包括用户点击某一菜单项时的相关句柄函数。
ContentItem 对象在运行于不同计算机上的小工具间传递，并且可以构成 contentArea 对象所包含的用户界面元素。
DetailsView 是一个用户界面功能，该功能允许小工具在补充工具栏外的其他窗口/小工具中显示更多信息。小工具利用此功能还可从“详细视图”接收通知和事件。
framework 命名空间framework 命名空间实现了填充 Windows Scripting Host（Windows 脚本主机）留下的空隙的 API，对于小工具的实施非常有用。具体讲，framework.* 对象并非 basicElement 的子对象，并且不会出现在小工具 XML 用户界面对象定义中。framework 是用于查询系统信息的对象的命名空间，基本类似于 .NET；由 XML 定义的用户界面对象所调用的脚本会使用这些系统信息。
利用 framework 对象及其属性可以：
- 显示文件对话框的浏览。
- 加载图片文件。
- 获取当前光标位置。
- 获取系统内存空间和使用情况的相关信息。
- 获取系统无线性能及连接情况的相关信息。
- 设置和监控控制何时运行脚本代码的计数器。
- 获取系统电源和电池电量的相关信息（总电量及剩余电量）。
- 获取系统处理器的相关信息。
- 获取系统的屏幕尺寸。
最后，还有其他两个定义的对象，它们仅用于 Framework 命名空间内的类型：
- point：表示“点”，具有 x 坐标属性和 y 坐标属性。
- size：表示对象的尺寸，具有高度属性和宽度属性。
作为可以如何使用 framework 对象的示例，我们编写了一个可显示膝上型电脑电池剩余电量的样例小工具：
<view width="200" height="200" onopen="view_onopen()">
<script language="jscript"><!--
function view_onopen()
{
setInterval( "update_battery()", 1000 );
}
function update_battery()
{
percent_used.innerText = system.power.percentRemaining + "%";
}
--></script>
<div background="#FFFFFF" width="200" height="200"/>
<label name="percent_used" align="center" valign="middle">0%</label>
</view>
我们定义了包含两个要素的 200x200 像素视图：
- <div>，背景颜色为白色
- <label>，名为 percent_used，最初读数为 0%。
在加载小工具时，触发 view::onopen 事件，该事件调用 view_onopen()。该函数设置了间隔，以使得每秒钟调用一次 update_battery()。update_battery() 使用 framework 命名空间的 system.power.percentRemaining 对象及属性更新 percent_used 元素的 innerText。
请注意，我们未将 framework. 放在 system.power.percentRemaining 前，是否这样做由您选择。
拖放用户界面对象
 |
这是在设计器中定义小工具用户界面的途径。只需在任一用户界面元素（共八个）上点击鼠标，并根据您希望该元素显示在小工具中的位置，将其向下拖动到白色显示区域内的相应位置。放开鼠标按钮，该用户界面元素即会出现在小工具中，并会成为当前选择的用户界面元素。作为选择的用户界面元素，其属性及属性值会显示在右侧的属性窗格中。只需在显示区域内点击某一用户界面对象，即可使其成为当前选择的用户界面对象。 用户界面对象具有 API 参考部分中介绍的所有属性、方法和事件。请记住，此处所示的对象均继承自 basicElement 对象，因此请在那一部分查看未针对各个对象指定的属性或事件的说明。八个用户界面元素为： - Div：用来设置小工具或用户界面元素的背景颜色，并提供一个连接点，以通过程序插入或删除包含元素中的用户界面元素。
- Image：指定视图中显示的图片。
- Button：按钮对象。
- Edit：指定小工具用户可以编辑文字内容的范围。
- Check：复选框对象。
- Link：定义 HTML 链接。
- Text Label：固定文本标签对象。
- Content：ContentArea 包容 (containment) 对象.请参阅 API 参考了解其使用方法。
progressbar 和 object 用户界面元素在设计器拖放元素时不可用，但可在 XML 代码中进行定义。请记住，设计器不允许直接编辑小工具的 XML 文件，因此您应使用外部编辑器程序。 |
元素窗格
在显示窗格中添加了一个或多个用户界面元素后，您可以通过以下两种方法之一选择元素：
- 在显示窗格中单击相应元素。
- 在元素窗格中点击其名称。
在某一对象被首次放入显示窗格时，它在元素窗格中显示为 view 元素的子元素，并且仅使用类型作为标识符。因此，例如，如果您将 Button 元素拖放到显示窗格中两次，元素窗格中会显示两个项目，并且两者均通过 button 指定。如果您赋予某个元素名称，例如 Button1，则该元素在元素窗格中会显示在表单 button (Button1) 内。 请注意，在设计器中只有一种途径可以访问 view 对象的属性和事件，即在元素窗格中点击 view 项。 |  |
属性窗格
属性窗格显示了当前选择的用户界面对象的属性及属性值。在该窗格内，您还可以修改对象的属性值，及选择与其事件相关的函数。 要修改属性值，只需点击其名称或值。输入选项取决于属性类型。
- 如果为布尔属性，则其值会变为一个小的下拉菜单，其中提供了 true 和 false 两个值。点击您希望赋予该属性的值即可。
- 如果为数字或文本值属性，则只需在值字段内键入新值，并按下 Enter 即可。 一些属性值，例如 mask 或 div 的 background，也可以为字符串或文件。对于该属性类型，会出现一个带有 3 个点的小框。如果点击该框，就会出现打开文件浏览器窗口，这样您就可以选择作为属性值的文件。如果您需要使用字符串值，只需在值字段内键入字符串，并按下 Enter 即可。
根据需要，显示内容会发生更改，以反映用户界面对象的新属性值。 请注意，cursor 等一些属性所允许的值集是确定且有限的。设计器不会查看您输入的值是否属于该属性所允许的值集。但是，在您显示视图时，不在值集的值会引起错误。 另请注意，可通过在元素窗格中选择进行访问的总体 view 对象都具有自己的属性和事件集。例如，如果您想要更改视图本身的大小，请在元素窗格中点击 view，然后在属性窗格中更改 height 和/或 width 值。 对于事件，只需在其值字段中输入小工具所包含的脚本文件中定义的函数的名称即可。例如，对于 view 的 onOpen 事件，可以在其值字段内键入 main.js 中定义的函数 view_onOpen()。 |  |
脚本窗格
本窗格显示了当前显示的 XML 文件中小工具所用的所有脚本文件。在完成小工具的设计后，这些脚本文件会和用户界面 XML 及图片文件压缩到一起。默认情况下，该窗格最初仅包含 main.js 文件，但您可以添加其他脚本和/或删除 main.js 要向脚本窗格中添加脚本文件，请点击三个图标中居左的纸张图标。这会打开以您的小工具文件夹开始的文件浏览器（设为仅显示脚本文件）。找到您要添加的脚本文件，并点击打开。请注意，脚本文件应已存在，您才可以在此处添加它。与 File-> 命令不同，该操作会将脚本文件复制到项目文件夹中，并让设计器将其显示在文件窗格中。它还会在显示窗格中当前活动的小工具 XML 文件中加入 <script src="filename" /> 行。因此，例如，如果 main.xml 处于活动状态，<script src="filename"/> 行仅会添加到 main.xml 中，而不会添加到 options.xml 中。 在脚本窗格中，通过点击选择某一脚本文件后，您可以：
- 点击中间的打开文件图标打开文件，以进行编辑。这会添加一个以文件名为标记的顶部标签。这一操作还相当于点击了这一新标签，会将显示窗格更改为针对该文件内容的编辑窗格。
- 通过点击右侧 X 图标从脚本窗格中删除文件。请注意，这会立即删除脚本，且不会显示任何确认对话框，但同时，该脚本的文件仍会显示在文件窗格中，且仍将会压缩为小工具的一部分，除非您还通过外部浏览器工具从小工具的文件夹中删除了相应文件。
脚本窗格不是显示项目文件夹中存储的脚本文件，而是显示当前显示的视图定义 XML 文件中所用的脚本，这一点非常重要。 如果您在通过文件->新建项目创建 main.xml 文件后立即查看它，则在其 <view> 元素中会包含 <script src="main.js" /> 行。main.js 还会列于脚本窗格以及文件窗格中。 如果您从脚本窗格中删除 main.js，则 <view> 元素中的 <script src="main.js" /> 会消失，表明小工具的视图无法再获取该文件中定义的函数的信息。文件本身仍存在于项目文件夹中，并应通过外部文件浏览器删除（如果您希望删除该文件），否则，它会与其他项目文件一起压缩到 .gg 文件中。 最后请注意，默认情况下创建新项目时，main.xml 会自动包含 <script src="main.js" /> 行，而 main.js 会包含 main.xml 所用的 view_onOpen() 函数的定义。如果您从脚本窗格中删除 main.js，却不提供替代函数定义，也不重新编写 main.xml，使其不再使用 view_onOpen()，则会出现错误。 |  |
菜单命令
在设计器窗口顶部共有五个带有下拉菜单的命令：文件、编辑、视图、项目和帮助。下面我们分别详细介绍这些命令。 |  |
文件菜单命令
文件包含七个菜单命令：
- 新建项目：打开另存为对话框，以让您指定存放新项目的文件夹的位置及其名称。点击 确定后，新项目即会出现在设计器窗口中。注意：如果某一项目已显示在设计器窗口中，在打开新项目前，不会要求用户保存项目。Cntl-Shift-N 为键盘等价命令键。
- 打开项目：打开浏览文件夹对话框，供您用来查找现有项目文件夹。选择文件夹后，点击确定。如果所选文件夹不包含 main.xml 文件，则会弹出错误消息，并退出操作过程。否则，所选项目会在设计器窗口中打开。Cntl-Shift-O 为键盘等价命令键。
- 关闭项目：关闭当前项目，设计器窗口显示为空白，仅保留顶部菜单命令。请注意，该命令不会让您保存当前打开的项目。该命令没有键盘等价命令键。
- 打开：打开已设为显示 XML 文件的文件浏览器。选择并打开文件会创建以相应文件名为标记的新的顶部标签，同时会选中新标签，并在显示窗格区域内显示文件的内容。请注意，新文件不会被添加到显示在文件窗格的小工具文件夹中，因为该文件并不在项目文件夹内。要向项目文件夹中添加文件，请使用 Windows Explorer 等外部文件浏览器。Cntl+O 为键盘等价命令键。
- 保存：保存所有打开的小工具文件。在编辑文件或更改用户界面对象的属性时，需要使用该命令。Cntl+S 为键盘等价命令键。
- 关闭：立即关闭当前显示在显示窗格中的文件，并删除该文件的顶部标签。文件本身仍在文件窗格中。Cntl+F4 为键盘等价命令键。
- 退出：弹出窗口，询问您是否保存对 main.xml 文件的更改。在您点击是或否后，小工具设计器即会关闭。Alt+F4 为键盘等价命令键。
另外，所有最近的文档都会显示在菜单部分退出命令上方的相邻位置。点击最近项目会在设计器中将其打开。 |  |
编辑菜单命令
编辑包含六个菜单命令：
- 撤消：还原您在设计器中执行的操作，例如更改属性值、移动用户界面对象、创建新对象等等。您可以连续进行多次撤消，从而撤消一系列操作。Cntl+Z 为键盘等价命令键。
- 恢复：如果您刚刚执行了撤消操作，该命令会恢复最后一次撤消的操作，否则该命令显示为灰色。如果您连续进行了多次撤消，则可以连续进行多次恢复，以还原设计器状态。Cntl+Y 为键盘等价命令键。
- 剪切：标准剪切操作，该命令作用于在显示窗格中选择的用户界面元素。Cntl+x 为键盘等价命令键。
- 复制：标准复制操作，该命令作用于在显示窗格中选择的用户界面元素。请注意，在复制用户界面对象时，会完全复制包括所有属性值在内的所有内容。因此，例如，如果您复制名为 Button2 的按钮，则复制的内容还会包含值为 Button2 的名称属性。在元素窗格中，两个按钮外观完全相同。Cntl+c 为键盘等价命令键。
- 粘贴：标准粘贴操作，该命令作用于在显示窗格中选择的用户界面元素。Cntl+v 为键盘等价命令键。
- 删除：标准删除操作，该命令作用于在显示窗格中选择的用户界面元素。DEL 为键盘等价命令键。
|  |
视图菜单命令
视图包含五个菜单命令：
- 刷新：刷新设计器窗口中的各种对象和窗格。最为重要的是，该命令会重新初始化小工具的所有全局变量和属性值，这样，就会从头开始执行全局范围的代码。从本质上讲，该命令会将小工具重置为最初状态，这在测试小工具时非常有用。F5 为键盘等价命令键。
- 下一个标签：等价于点击当前所选标签右侧的顶部标签。如果当前选择的是最后一个标签，则相当于转而点击第一个标签。Cntl+Tab 为键盘替代命令键。
- 上一个标签：等价于点击当前所选标签左侧的顶部标签。如果当前选择的是第一个标签，则相当于转而点击最后一个标签。Cntl+Shift+Tab 为键盘替代命令键。
- 调试控制台：在设计器窗口底部打开调试控制台（占用通常的窗口内容所用的空间；若要将其他内容恢复为之前的大小，需要重新调整窗口大小）。视所选中的复选框而定，此处会显示预览/运行小工具时生成的调试、信息、警告和或错误消息。您还可以选择是否显示所出现的消息。要隐藏调试控制台，只需再次点击调试控制台菜单项。
- 预览窗口：更改显示窗格，使其显示运行模式下的小工具，以便于您测试用户界面和查看其工作情况。等价于点击预览顶部标签。
|  |
项目菜单命令
项目包含三个菜单命令：
- 设置：打开项目设置对话框。F3 为键盘等价命令键。
- 添加选项视图向项目中添加 options.xml 文件，并在顶部添加 options.xml 标签；由于每个项目只可以定义一个 options.xml 文件，因此，添加选项视图会显示为灰色。点击该命令后，应采用与主视图相同的方式创建并测试选项视图及其用户界面。
- 建立包：将小工具的文件压缩到 Project_Name.gg 文件中，以供分发。F7 为键盘等价命令键。
|  |
帮助菜单命令
帮助包含两个菜单命令：
- 用户指南：在浏览器窗口中打开本文档。
- 关于：显示包含关于设计器的有限信息的弹出窗口。
|  |
补充工具栏小工具之间的通信
满足以下条件时，运行在不同计算机上的补充工具栏小工具之间可以进行通信：
- 应为相同的小工具；Tic-Tac-Toe 小工具可以与另一 Tic-Tac-Toe 小工具通信，但不能与便笺簿小工具通信，反之亦然。
- 进行通信的小工具的所有用户都应登录 Google Talk。
Google Talk 担当补充工具栏小工具的通信媒介。在用户登录 Google Talk 后，小工具就可以获得用户当前在线的 Google Talk 朋友列表。获得在线朋友列表后，小工具即可与运行于在线朋友计算机上的同一小工具进行数据发送和接收操作。如果朋友没有安装补充工具栏，小工具则会向该朋友发送一条文本消息。
在向基于脚本的小工具添加通信功能时，要发送数据和设置小工具接收数据时调用的句柄，都会用到 googleTalk 全局变量。
在发送数据时，第一步是引用 googleTalk 的 friends 属性，该属性会获取包含您的 Google Talk 在线朋友的 friend 对象的队列。
friend 对象具有五个属性：
- name：Google Talk 中显示的名称。
- user_id：Google Talk 用户 ID，会作为数据/消息接收参数传递给数据/消息发送方法。
- email_address：朋友电子邮件地址。
- has_sidebar：布尔指示符，指出朋友是否安装了补充工具栏。在尝试向可能不存在的工具栏发送数据前，应查看该属性。
- status：朋友的 Google Talk 状态：在线、空闲或忙碌，此处分别以 0、1 或 2 表示。
在脚本获得 Google Talk 朋友队列后，即会利用以下两种方法之一向朋友发送数据：
- SendTalkData(friend_id, data)：向由 friend_id 的补充工具栏确定的朋友发送数据字符串（最长 2000 个字符）。具体讲，是向朋友补充工具栏中与调用该方法的小工具相同的小工具发送数据。
- SendTalkText(friend_id, message)：向用户 ID 为 friend_id 的 Google Talk 用户发送最多 2000 个字符的文本消息。该方法常用于朋友未安装补充工具栏时。
要接收数据，需要为某一函数建立关联，以与 googleTalk 的 onReceiveTalkData 函数句柄一同进行处理。函数的签名应为 name(friend_object, data_string)。在小工具收到数据时即会调用该函数，因此在编写时，应使其能够处理其他小工具可能发送的任何及全部消息。
使用通信 API 的脚本工具不应执行收到的数据，这一点是通过调用 eval() 实现的。导致这一问题的原因是恶意用户可能会对小工具进行修改，以发送在朋友计算机上执行的脚本。收到的脚本会在本地权限下运行，因此可以访问本地文件和资源。为防范这一情况，需查看 eval() 调用，以确保其没有评估收到的数据。
要了解小工具通信的示例，请查看 SDK 中提供的 Tic-Tac-Toe 示例代码。
用户界面与可用性指南
在设计小工具时，请记住以下一般原则：
- 小工具应简单、简洁、简短。
补充工具栏的空间资源非常有限，因此要仅使用确实需要用来显示信息的空间。简单的调色板提供了更为清晰的外观，同时最大限度地降低了与其他小工具在感觉上的不协调。
- 开发期间测试易用性。
在开发小工具功能时邀请他人使用您的小工具。在它们发现不协调或不易使用的情况时，请重新考虑用户界面方面。特别是要确保帮助内容清晰、有用、全面。
用户希望与补充工具栏小工具的交互在小工具间保持一致性。以下部分将指出在所有补充工具栏小工具间均应保持一致的视觉线索与操作。
一般设计
您的小工具应提供尽可能多的替代操作和信息。具体指：
- 为小工具的命令提供鼠标替代操作和键盘替代命令键（包括为所有菜单命令提供键盘快捷键）。
- 支持工具提示。
- 提供详细视图窗格（如果需要）以及可用操作的右键点击上下文菜单。
鼠标输入
由于用户通过鼠标与大多数小工具进行交互，因此，与用户界面相关的鼠标输入在整个补充工具栏内更应保持一致，以避免造成混乱。以下视觉线索会告知用户三个主要平铺窗格元素类型所支持的点击类型。
- 项目：显示小工具的主要内容，例如在新闻小工具中的文章。
- 单击选择项目并打开其详细视图。
- 双击在新的应用程序窗口中打开项目，同时在补充工具栏中选中该项目。
- 鼠标悬停临时突出显示项目。
- 窗口小部件：包括按钮、复选框、星标等等，在被点击时会执行某些操作。
- 仅单击！我们保留双击，将其用于打开项目。
- 鼠标悬停和鼠标点击状态与正常状态外观不同。
- 看上去应可点击，例如使用带有三维阴影的图形。
- 同时作为窗口小部件的文本应满足以下两点，以与普通文本区分开来：
- 在可点击文本旁显示图标（请参见下例“删除”按钮）。
- 其鼠标悬停状态看上去应可点击或与按钮相似。
- 窗口小部件不是项目或项目的一部分。点击窗口小部件不应打开项目的详细视图。
- 针对文本和图形使用所支持的 DrawItemBackground（使用不同标记设置），创建在整个补充工具栏内外观相同的按钮。
- 窗口小部件示例：
| | 正常状态 | 鼠标悬停 | 鼠标点击 |
复选框
（执行项目小工具） |  |  |  |
删除按钮
（详细视图） |  |  |  |
- 状态指示器：显示辅助信息的图标或图形。
- 如果是项目的一部分，则会继承项目的所有鼠标行为
- 图形通常是不可点击的，因此，在鼠标悬停或鼠标点击时应不会改变。
- 状态示例（收盘价格、网络活动、天气云量）：
显示
图形和图标
- 应为小工具提供两种大小的图标。图标设计应该易于理解，并与小工具的功能相适应。
- 12x12 像素：显示在小工具的标题栏中
- 32x32 像素：显示在关于这一小工具对话框和快讯用户界面中（如果小工具支持）。
- 小工具中的图标应该为 12x12 像素。由于尺寸较小，请使用简单图形和调色板，以便于用户快速识别小工具。
- 以下 12x12 图标集用于默认补充工具栏小工具集。您应该使图标样式与这些图标相符合，它们具有简单完整的图形，且通常由单一主色阴影组成。图片本身以 2D 平面形式代表了小工具的内容。每个图标的主色阴影都具有 1 像素的边界。
颜色
- 请慎用颜色。如果可以，请使用灰色阴影。
- 请勿使用太亮的颜色，或对比度过高或过低的组合。尽量避免引起视觉疲劳。例如，左侧图片颜色运用较好，右侧图标则难以阅读。
- 不要仅仅依靠颜色进行区别，因为如果用户色盲，会出现问题。此示例同时使用颜色（红/绿）和文字 (+/-) 表示股票价格的改变方向。
文本
- 用户指定的系统字体和字体大小同时会用于补充工具栏的文本显示。
- 标准文本是黑色，重要性较低的文本颜色为 navy（深蓝）[#224499 或 rgb(34, 68, 153)] 或 gray（灰）[#666666 或 rgb(102, 102, 102)]。
- 尽量避免使用粗体文本，因为相对于补充工具栏的其他部分过于突出。
格式和布局
补充工具栏可以有四种不同的视图；常规、最小化、扩展和详细。
- 常规视图：常规外观。
如果您具有网络剪辑等项目列表，则可以使用 API 提供的列表布局。如果只显示一个项目，例如一张图片，则使用单项目列表布局。只通过查看此视图内容，小工具的用途就应该一目了然。
请记住，根据补充工具栏的宽度，您所显示的信息可能更多或更少。应该尽量避免使用滚动条，而是使用项目的扩展视图。
尽量清晰明了地表示项目的类型。例如，文件项目应该在名称旁边带有文件类型图标。对于较大的文本（例如电子邮件或网页）的摘录，应该在第一行显示标题，附带该项目来源和日期等主要信息。
- 最小化视图：即仅显示标题栏。
通常，标题栏只显示小工具的图标和标题。您也可以不显示标题，而是逐一循环显示小工具的简短项目，例如您的股票及其价格。
- 扩展视图：补充工具栏旁边完全最大化的视图。
通常用于显示所有小工具项目的完整列表，如果有很多项目需要显示，可以使用垂直滚动条。
- 详细视图：特定小工具项目的详细信息。
通过点击任何项目，就可以从小工具的常规或扩展视图启动此视图，它可以显示尽可能多的信息。
点击一个项目的标题就可以在相应的应用程序中打开它，例如在浏览器中打开一张网页。
国际化
即使您无法提供任何其他语言的文本，在编写小工具时，也应该使它的文本和标签能以多种语言显示。今后，或许其他人能够提供。您还可以为不同语言的用户指定不同图片、视图布局甚至脚本。
首先，让我们看看语言。要支持多种语言，需将所有小工具用户界面中可见的特定语言的字符串放在名为 strings.xml 的文件中，此文件在以相应语言 ID 命名的子目录中。此文件包含针对特定语言字符串的指定变量。在小工具定义和代码中不使用特定语言字符串，而是使用这些变量。例如，“世界您好”的英语 strings.xml 文件包括：
<strings>
<strTitle>HelloWorld!</strTitle>
<strHello>HelloWorld!</strHello>
<strSnippet>一些项目信息。</strSnippet>
<strAboutText>
HelloWorld!插件。此处为版权信息。此处为详细说明
</strAboutText>
<strDescription>Says Hello World</strDescription>
</strings>
这样，您在“世界您好”小工具的脚本代码中，为“HelloWorld!”标题设置了视图的 caption 属性，如下所示：
view.caption = strTitle;
如果在您的 XML 或 .gmanifest 文件中设置了 About 文本，如下所示：
<aboutText>&strAboutText</aboutText>
请注意，在代码中，您只需使用来自 strings.xml 文件的元素名。在 XML 中，您需要在元素名之前加上 &。
如果您编写的小工具同时具有英语和法语版本，应该将文件放在以下目录树中：
<GD dir>/Plugins/YourGadget
|
|---- gadget.js
|
|---- gadget.gif
|
|---- 1033 (美国英语语言 ID)
| |
| `-- strings.xml
|
`---- 1036 (法语语言 ID)
|
`-- strings.xml
补充工具栏首先检查具有与当前系统所使用的语言 ID 相同的目录。如果存在，它将加载该目录的 strings.xml 文件。如果无法找到该文件，默认情况下将加载 1033（美国英语）目录的 strings.xml 文件（如果存在）。
同样，您现在可以将图片、标记、脚本等等放置在此本地化文件夹中，Sidebar 将尝试使用以上规则加载它们。这样，例如，如果您的小工具针对当地语言需要不同图片，可以按以下步骤操作：
<img src="some_image.png"/>
补充工具栏将首先尝试加载 some_image.png，如果系统语言为法语，它将在法语本地化目录中查找此图片（1036\some_image.png），然后退回英语目录 (1033\some_image.png)。
您可以将内容放置在本地化目录中，而不是主目录中，包括：
- main.xml：如果具有使用不同语言的不同布局。
- options.xml：如果具有使用不同语言的不同布局。
- anything.js：如果具有使用不同语言的不同脚本。
如果您希望所创建的小工具在大多数地方都支持默认行为，但是对不同语言具有不同行为，可以：
- 将 gadget.xml 放置在 gadget.gg 文件的根文件夹中。
- 将其他内容放置在 gadget.gg 文件的 1033\ 文件夹中。
- 将不同语言中需要替换的内容放置在特定语言的文件夹中。
点击此处可以获得所有语言 ID 号码的列表。
API 参考
对象参考
此部分显示了 Google Gadgets API 中与脚本相关的不同对象，包括它们的属性、方法和相关事件。注意，许多对象继承了 basicElement 的属性、方法和事件。
同样，如果说一个方法返回了一个元素，这意味着在小工具的 XML 定义中定义了一个元素，它继承自 basicElement。
gadget.debug
列出了可用于开发和调试小工具的 API。要以调试模式运行，请解压缩您的小工具，并双击所获得的文件中的 gadget.gmanifest 文件。 |
| 方法 |
| 名称和参数 | 说明 | 返回值 |
| error(string Message) | 当小工具以调试模式运行时，在调试控制台中作为错误消息显示字符串消息。 | void |
| trace(string Message) | 当小工具以调试模式运行时，在调试控制台中显示字符串消息。 | void |
| warning(string Message) | 当小工具以调试模式运行时，在调试控制台中作为警告显示字符串消息。 | void |
gadget.storage
提供对小工具包内容的访问权。 |
| 方法 |
| 名称和参数 | 说明 | 返回值 |
| extract(string filename) | 将文件从小工具包解压到临时文件夹，并返回该解压文件的完整路径。 | 字符串 |
| openStream(string filename) | 通过小工具包打开一个文件，并作为流返回内容。 | 流 |
| openText(string filename) | 通过小工具包打开一个文件，并作为字符串返回内容。 | 字符串 |
view
注意：与其子对象/内容对象不同，view不从 basicElement 继承。
您必须在单独的文件中为小工具的每个面板用户界面定义 view 对象。 |
| 属性 |
| 名称 | 说明 | 类型 | 读/写 |
| caption | 此视图的标题，默认情况下当小工具处于浮动/扩展模式时显示此标题，当小工具位于补充工具栏中时不显示此标题。另请参阅 showCaptionAlways 属性。 | 字符串 | 读-写 |
| children | 返回包含此视图元素的直接子元素的集合。它们全部是 basicElement 的子对象。只能通过脚本访问，不能通过 XML 定义访问。 | 元素 | 只读 |
| event | 事件句柄脚本获得 event 对象的方式。 | 事件 | 读 |
| height | 设置或返回视图高度，以像素表示。 | 整数 | 读-写 |
| width | 设置或返回视图宽度，以像素表示。 | 整数 | 读-写 |
| resizable | 值为 true 时，用户可以调整视图的大小。 | 布尔 | 读-写 |
| showCaptionAlways | 值为 true 时，补充工具栏一直显示此视图的标题（在caption 属性中指定）。默认情况下或当此值为 false 时，如果小工具在补充工具栏中则不显示此标题，如果小工具处于浮动或扩展模式则显示此标题。 | 布尔 | 读-写 |
| 方法 |
| 名称和参数 | 说明 | 返回值 |
| void alert(string message) | 显示包含消息字符串的消息框。 | void |
| element appendElement(string xml) | 解析所提供的元素定义（以 XML 格式给定），并将此元素附加为此视图的最后一个子视图。 | 新元素。 |
| integer beginAnimation(string script, integer startValue, integer endValue, integer duration) | 启动动画计时器。此计时器运行 duration 毫秒。在此时间段内使用 StartValue 和 EndValue 之间的值定期执行脚本。 | 可用于取消此动画的标识符。
注意：调用 Callback 的次数由系统的性能和当前负载决定。最高为 100 fps。 |
| void cancelAnimation(integer Token) | 取消当前运行的动画。Token 是 beginAnimation 返回的标识符。 | void |
| void clearInterval(integer Token) | 取消间隔或超时。 | void |
| boolean confirm(string message) | 显示包含消息字符串的确认框。如果按“确定”，返回 true，否则返回 false。 | 布尔 |
| element insertElement(string xml, element InsertBefore) | 解析提供的 XML，并将此元素插入紧挨 InsertBefore 元素之前的位置。 | 新元素。 |
| void removeElement(element Item) | 删除指定元素。 | void |
| void resizeBy(integer width, integer height) | 根据视图当前的宽度和高度，将视图大小更改指定的宽度和高度。以像素为单位。 | void |
| Void resizeTo(integer width, integer height) | 将视图大小更改为指定的宽度和高度（以像素为单位）。 | void |
| integer setTimeout(string Script, integer Duration) | 创建单次运行计时器。在 Duration 毫秒之后脚本将执行一次。 | 可用于取消超时的令牌。 |
| integer setInterval(string Script, integer Duration) | 创建一个永久运行计时器。在取消之前，脚本将每 Duration 毫秒执行一次。 | 可用于取消间隔的令牌。 |
事件
|