Opera Widget 规范 1.0 第三版

Posted 03/01/2009 - 22:42 by daitao

Widget

By Opera Software · 21 May, 2008

本文翻译自 Opera Widgets Specification 1.0 third edition

摘要

本文介绍 Opera Widget 1.0，第三版。本文包含 Opera Widget 的各个方面，包括封装格式、配置文件 config.xml 和脚本语言接口。

本文的地位

本文档和其附件介绍了如何创建和运行跨平台跨设备的 Opera Widget 。

1. 引言

本规范的目的是为实现 Opera Widget 提供参考。此规范基于 Opera 9.50 平台的特性。

1.1 Conformance Requirements

本文的措辞 ”必须”, ”不能”, ”要求”,
”可以”, ”不可以”,
”应该”, ”不应该”,
”建议”, ”可能”, 和
”可选” 的含义见 [RFC2119].

除非特别指出，本文被认为是 widget 的标准规范。

2. Widget 封装

2.1 文件格式

Widget 是按照 [ZIP] 文件格式压缩的压缩包文件，但 widget 文件不支持 [ZIP] 文件格式中的 ‘Deflate64’ 压缩算法。

2.2 Widget 文件

每一个 Opera Widget 必须包含下面两个文件：

config.xml —— 包含初始化 widget 所必需信息的配置文件。此文件总包含 widget
名称和尺寸，也可以包含以下关于 widget 的信息：
- Widget 描述
- 作者信息
- Icon 图像文件
- 安全信息
index.html —— 此文件是
widget 的主要文件。它被显示在 config.xml 文件所描述的视图中。像一般的网页一样，此 HTML 文件可以引用外部内容。可引用的内容包括但不限于 script 脚本、CSS
样式表文件和图像。

2.3 Widget 文件夹结构

在把 widget封装成 zip 文件时，作者必须选择以下两种结构中的一种来组织文件：

config.xml 和 index.html 文件放在 .zip 文件的根目录 ，脚本文件和图像等其他资源放在根目录或者子目录中。
另一个方法是把属于 widget 的所有的文件都放在根目录的一个文件夹中。此文件夹的名称应该和 .zip 压缩包文件同名。若使用这种方法，根目录不允许有多个文件夹。如有多个文件夹，加载 widget 一定会 失败。

Widget 被载入以后，会将 config.xml 所在的目录设为 widget 的根目录。

2.4 Content-Type

Web 服务器向用户提供 widget 时，widget 的 content-type 必须是 application/x-opera-widgets 。

2.5 文件扩展名

Widget 应该使用 .wgt 扩展名，以便被正确的识别。但是，只要如上文所述正确设置 content-type ，应该也可以使用其他的扩展名，如 .zip 。

3. Widget 配置文件：config.xml

客户端运行 widge t所需的信息都被保存在名为 config.xml 的文件中，在本文档 Widget 封装一章中详细介绍过其存放位置。此配置文件包含创建 widget 初始视图所需的信息。config.xml 文件是符合 [XML10] 规范的 XML 1.0 文档。

下面的例子显示了 config.xml 至少包含的内容： widget 名称和初始界面大小（ 300×300 CSS 像素）：

 <widget>
<widgetname>
      Hello World!
</widgetname>
<width>
      300
</width>
<height>
      300
</height>
</widget>

3.1 空格

config.xml 文件的元素所包含的空格被按如下规则处理：

语句前后空格被自动删除。
多个空格字符被处理为一个空格字符。

此处理方法与 [CSS21] 规范中的white-space 属性为normal时一致。

当处理 config.xm l时，Opera 会忽略所有的元素的首尾的空格，相当于设置 textContent DOM 属性值。

3.2 `widget` 元素

widget 元素是 config.xml 文件的根元素，widget 必须是配置文件的唯一的根元素。

3.2.1 `widget` 元素的可选属性

defaultmode 属性

widget 元素可以设置 defaultmode 属性，其作用是设置 widget 的默认显示模式。合法的属性值为：

widget: widget 可以控制窗口大小，但是不含 chrome。
application: widget的窗口大小由 widget 引擎确定，config.xml 中设置的 widget 大小仅作为参考。widget 引擎应该显示 chrome。
fullscreen: 此模式与 application 模式相同，只是 widget 使用所有可用区域显示。客户端可以
显示chrome。

如果 widget 不支持指定的模式，widget 会按照
application, fullscreen 和 widget 的顺序依次使用备用模式。

若不设置此属性，则默认属性值为 widget。

dockable 属性

dockable 属性表明 widget 是否支持浮动模式，直接显示整个网页，而不是只显示包括 widget 状态和 icon 等的有限的信息。

dockable
属性的合法值：'yes'， 'true'
和 'dockable' 被认为是可浮动的 widget（注意区分大小写）。所有其他值被认为是 false，意味着 widget
不支持浮动模式。

transparent 属性

如果 widget 不需要透明特性，如整个 widget 视图都是不透明的，可用 transparent 属性来控制 widget 是否使用透明特性。

transparent 属性的合法值有 'yes', 'true' 和 'transparent'（区分大小写），这表示 widget 是可透明的。其他所有的值都被解释为 'false'，意味着 widget 是完全不透明的。

未定义此属性时，若当前的 widget 模式是
'widget'，则默认为支持透明；若当前模式为 'application' 或 'fullscreen'，widget 被默认为不支持透明。客户端可能按照运行平台特性重新定义此值。

3.3 `<widget>元素必需的子元素`

3.3.1 `widgetname` 元素

widgetname 元素必须作为 widget元素的子元素出现在配置文件 config.xml 中，而且必须包含一个字符串以给 widget 起一个人类可理解的名称。此名称将被显示在应用程序菜单中，以提供 widget 的描述。

3.3.2 `width`
元素

width 元素应该作为 widget 元素的子元素出现在配置文件 config.xml 中。在去处首尾的空格后，此属性值必须是能被解释为整数的字符串，只包含数字
[0–9]。

此整数值被解释为 widget 沿水平轴的尺寸，单位为规范 [CSS21] 4.3.2章节所述的 CSS 像素。此值应表示 widget 的内部宽度，或者水平轴方向的所有可绘制区域宽度。

若未定义此属性或此属性值不合法，宽度被默认为 100。

若运行 widget 的平台不允许 chromeless 窗口被拖动，请参考 virtual
viewports 。

3.3.3 The `height`
element

height 元素应该作为 widget 元素的子元素出现在配置文件 config.xml 中。在去处首尾的空格后，此属性值必须是能被解释为整数的字符串，只包含数字 [0–9]。

此整数值被解释为 widget 沿竖直轴的尺寸，单位为规范 [CSS21] 4.3.2章节所述的 CSS 像素。此值应表示 widget 的内部高度，或者竖直轴方向的所有可绘制区域宽度。

若未定义此属性或此属性值不合法，宽度被默认为 100。

若运行 widget 的平台不允许 chromeless 窗口被拖动，请参考 virtual viewports 。

3.4 `<widget>的可选子元素`

3.4.1 `widgetfile` 元素

widgetfile 元素是 widget 元素的可选子元素。如被定义，此元素的作用是指出 widget 的起始页的位置。此元素的值必须
是指向起始页的合法的相对路径，且此路径必须采用 URL 编码。

3.4.2 `author` 元素

author 元素是 widget 元素的可选子元素。如被定义，此元素的作用是提供 widget 作者的信息。此元素可以有若干子元素，定义如下：

3.4.2.1. `name` 元素

若 author 元素被定义，name元素也应该被定义。若定义 name 元素，必须作为 author 元素的子元素，并且其值必须为字符串表示的人类可理解的 widget
作者名称。

3.4.2.2. `organization` 元素

若 author 元素被定义，organization 元素也可以被定义。若定义 organization 元素，必须作为 author 元素的子元素，并且其值必须为字符串表示的人类可理解的组织名称。

3.4.2.3. `email` 元素

若 author 元素被定义，email 元素也可以被定义。若定义 email 元素，必须作为 author 元素的子元素，并且其值必须为字符串。此字符串应表示 [RFC2822] 规定的合法 e-mail 地址。此地址应该为可以联系到作者的有效 e-mail 地址。

3.4.2.4. `link` 元素

若 author 元素被定义，link 元素也可以被定义。若定义 link 元素，必须作为 author 元素的子元素，并且其值必须为字符串。此字符串应表示 [RFC3987].规定的合法 IRI 。建议 IRI 是可解析的。此元素的用处是提供用户可访问的 IRI 。

3.4.3 `description` 元素

description 元素是 widget 元素的可选子元素。若被定义，其应该包含以字符串表示的人类可理解的描述 widget 的短文。

3.4.4 `icon`
元素

icon 元素是 widget 元素的可选子元素。此元素被用于提供 widget 可使用的 icon文件，当操作系统或 widget 播放器需要表示 widget 时可以使用此 icon 文件表示。

此元素必须包含符合 [RFC3987] 规范的相对IRI ，根目录为 config.xml
文件所在的目录。

若被定义，此 IRI 必须能被解析，且必须指向以下列格式中的一种表示的图像文件：[PNG10], [GIF89] 或 [SVG]。

icon 元素可以包含 width 和 height 属性。

config.xml 可以包含多个 icon 元素。若定义了多个 icon 元素，widget 引擎可以选择最适合显示区域的 icon 图标显示，即使没有 icon
能精确匹配显示区域尺寸。

width: 此属性值应为表示 icon 宽度的无符号整数，其单位是设备像素。
height: 此属性值应为表示 icon 高度的无符号整数，其单位是设备像素。

当客户端选择 icon 时，应该选择最能匹配 width 和 height
属性的 icon。若不能精确匹配，客户端应该选择最接近实际大小的 icon 显示。

若定义了多个同样大小的 icon 元素，Opera
应该选择最后出现在 config.xml 中的元素；widget 引擎也可能选择某种固定格式的 icon ，比如 PNG 格式，甚至在其它格式的图像可能更合适时仍会选择 PNG 格式的 icon。

3.4.5 `security` 元素

security 元素是 widget 元素的可选子元素，它可能出现在 config.xml 中。其目的是包含与安全有关的设置。security 元素的子元素如下所示：

3.4.5.1. `access` 元素

access 元素是 security 元素的可选子元素。access
元素的子元素用于声明 widget 可使用的协议、主机和端口。未定义的 access 子元素被解释为“所有”。比如若没有定义 host 原色，则表示 widget 可以访问所有主机。

另外，所有子元素都可以多次出现。下面列举了可用的子元素。

protocol: widget 可使用的协议。除 file 协议外的所有协议都可以使用。
host: host 元素表示 widget 可访问的主机名。主机名被完全匹配。这意味着定义可访问 www.example.com 的widgdt 不能访问 example.com 。此元素值也可以使用IP 地址。
port: port 元素表示 widget 可使用的端口。此值可以是一个整数、用"-"间隔的数字区间（ 例如 1024-2048）、或者用','间隔的数字列表（ 例如 80, 1337）。
path: path 元素表示可访问的 URI 。

3.4.5.2. `content` 元素

Widget可以使用第三方插件和 Java 程序。Widget
要想使用这些外部资源必须声明，方法是在 security 元素中加入 content 子元素。若 content 元素被定义，其必须包含以下两个属性中的一个，也可以 全部包含。

java 属性: 此属性值可以是"yes" 或"no"，注意不区分大小写。若
widget 想要使用 Java 资源，此值必须为"yes"。若未定义此属性，则默认为"no"。
plugin 属性: 此属性值可以是"yes" 或"no"，注意不区分大小写。若
widget 想要使用插件，此值必须为"yes"。若未定义此属性，则默认为"no"。

若 security 元素不含 content 元素，或 widget 未定义 security 元素，则 java
和 plugin 属性被默认设置为 ”no”。

3.4.5.3. 安全模型

Widget 访问安全模型归纳如下：

Widget 不能通过 file: 协议访问本地文件系统中的文件。
Widget 可以使用 http访问外部服务器，即使 config.xml 中未显式的定义此规则。
除非显式定义，widget 不能使用 http 之外的规则。Widget可以通过 https, ftp 或其他任何支持的协议 (除 file: )，但是必须在 config.xml 中的security元素中显式定义。
Widget 不能访问非默认端口(non-default port)，除非在 config.xml 中声明的端口。另外，wigdet 不能访问小于等于1023的非默认端口。
Widget 若访问过下面定义的 intranet 地址， 则不可以 继续访问非 intranet 地址。同理，widget
若访问过下面所列的地址以外的 IPv4 地址，不可以 继续访问下面所列的地址。

3.4.5.4. Intranet
的定义

以下 IPv4 地址区间被定义为 intranet：

10.0.0.0 至 10.255.255.255
172.16.0.0 至 172.31.255.255
192.168.0.0 至 192.168.255.255
169.254.0.0 至 169.254.255.255

这个范围之外的地址都被认为是 Internet 地址。

3.4.5.5. 安全模型举例

下面的安全模型实例指明：widget 可以通过 https 或 http 协议访问 example.com 和 example.org 主机的2048–4096端口，但是只能访问 ’/good’ 路径中的资源。另外，此 widget
可以使用 Java 程序，但不能使用插件。

 <security>
<access>
<protocol>http</protocol>
<protocol>https</protocol>
<host>example.com</host>
<host>example.org</host>
<path>/good</path>
<port>2048-4906</port>
<port>80,1337</port>
</access> <content java="yes" plugins="no"   />
</security>

3.4.6 `id`
元素

id 元素是 widget 元素的可选子元素。若被定义，此元素可能被用于表示 widget 的 id 。此 id 可能会被用于版本升级或者其他用途。id 格式要求如下三个
子元素：

host: 此元素为必需，且必须是合法的表示能下载此 widget 的域名。
name: 此元素为必需，且必须是对host来说的独一无二的字符串。
revised: 此元素为必需，且必须是 [W3CDTF] 格式的字符串，并且要求日期必须包含年和月。widget 作者可以自己选择此日期，只要能区分不同 widget 发布日期即可，但注意年和月是必需的。

4. Widget 模式

Widget 是客户端的 web 应用程序，其通常用于显示本地信息或者远程获得的信息的（通常显示在用户设备桌面上）或者像本地安装的程序一样运行。Widget 可以在不同的模式下运行。Widget 可能支持多种模式，但是只能以一种模式显示。

widget: widget 模式通常用于传统的桌面显示的 widget —— 通常这些 widget 都不含 chrome（不含用于改变窗口大小的控件也不含标题栏）。使用此模式的 widget 通常能自己控制整个窗口，这意味着它能随心所欲的改变窗口大小。若运行在比
widget 小的显示区域中，运行平台应该提供滚动机制或其他方式以便能使用整个 widget ，而 widget 仍按照设定的几何尺寸显示。
application: application 模式下widget 包含 chrome（包含移动和改变 widget 大小的控件），其被用于含有窗口管理的系统。此模式下运行的 widget 由用户或者运行环境控制窗口位置和窗口大小，但 widget 仍可以提供初始位置和大小信息。
fullscreen: 此模式与 application 模式相同，除了初始大小被运行环境设置为全屏之外。
docked: dock 模式，有时被称作 '微型 widget 模式'，在此模式下，widget 被显示为最小状态。通常在屏幕保护界面、列表视图和其他显示面积有限的时候使用此模式。在此模式下的 widget 通常不支持用户交互，用户只有激活 widget 并转为其他模式后才能继续用户交互。

4.1 Widget 模式的 CSS 扩展

若希望给每个模式单独设置样式，可以使用 -o-widget-mode CSS media 特性。它的值为上述四个预定义的 widget 模式，用于表明此样式适用于哪些模式。下面是几个例子：

在 application 模式下隐藏界面元素：


  @media all and (-o-widget-mode:application {
    /* We don't need to display fake user chrome controls, since
       real chrome is provided */
    .fakeChrome { display: none; }
  }

在浮动模式下改变字体大小：


  @media all and (-o-widget-mode:docked {
    body { font-size: 80%; }
  }

若不指定 -o-widget-mode 属性的值，则定义的样式适用于所有支持的模式：


  @media all and (-o-widget-mode) {
    div.friendlyMessage {
      content: "I will be displayed if I am a modern widget";
    }
  }

5. Widget 脚本接口

5.1 Widget 对象

5.1.1 用途

widget 对象的用途是为 widget 专用的功能提供接口，而普通网页使用的脚本不应该或者不能支持这些功能。widget 对象实现了 Widget 接口：

interface Widget {
  
      readonly attribute DOMString identifier;
      readonly attribute DOMString originURL;
      readonly attribute DOMString widgetMode;
    
      void openURL(in DOMString URL);
    String preferenceForKey(in DOMString key);
      void setPreferenceForKey(in DOMString value,
                                in DOMString key);
  
      /* Widget attention */
      void getAttention();
      void showNotification(in DOMString msg, in Function callback);
  
      /* Widget window managment; */
           attribute Function onshow;
           attribute Function onhide;
      void show();
      void hide();
  }

5.1.2 `identifier` 属性, `DOMString 类型`, 只读

DOMString 类型的 identifier
属性，表示当前 widget 实例的独一无二的 id 。其值必须是唯一的合法 DOMString。

5.1.3 `originURL` 属性, `DOMString` 类型, 只读

若 widget 通过除 file:// 外的协议被下载，此属性的值应为下载 widget 的所使用的 URL 。此属性值不应该被转义或被转换为 URL 编码。

5.1.4 `widgetMode` 属性, `DOMString 类型`, 只读

widgetMode
属性表示 widget 当前使用的显示模式。其值应该为下列值之一：widget, application,
fullscreen 或 docked。此值必须和当前显示模式一致。

5.1.5 `openURL`() 方法

openURL() 方法的参数为一个字符串，此字符串必须是 [RFC3987] 规范定义的合法 URL
。若此函数被调用时，若 URL 合法，则此 URL 被使用系统浏览器打开。

注意本规范的 security 章节介绍了openURL 可打开的 URL 的限制。特别指出以下规则：

Widget 不能使用 file: 协议
Widget 使用 openURL 访问过 Intranet 就不能再使用 openURL 访问 Internet。
Widget 使用 openURL 访问过 Internet 就不能再使用 openURL 访问 Intranet。
OpenURL 不接受相对 IRI，因此不能打开此 widget 内的文件。.

5.1.6 `preferenceForKey`() 方法

preferenceForKey() 方法的参数是字符串类型的 key 。当被调用时，此方法返回之前用 setPreferenceForKey 方法存储的 value 字符串；若此key 不存在，则返回 undefined。

5.1.7 `setPreferenceForKey`() 方法

setPreferenceForKey() 方法有两个字符串类型的参数，分别是 preference 和 key。被调用后，此方法把 key/preference
存储在设备中，以后可以使用 preferenceForKey()
方法查询。要删除以前存储的 key，只需要调用 setPreferenceForKey() 并置 key 参数为要删除的 key， preference 参数为 null 即可。

5.1.8 `getAttention`() 方法

getAttention()
方法没有参数也不返回值。其作用是通过某种方法引起用户注意。

引起用户注意的方法可能包括闪动任务栏图标、或提高 widget 紧急度。但 getAttention() 方法不应该 获取窗口焦点。

5.1.9 `showNotification`() 方法

showNotification() 方法有两个参数，第一个是字符串信息，第二个是回调函数——当通知被接收以后，就会运行此回调函数。

showNotification() 被调用后，系统会显示一个包含第一个参数的通知。此信息是 DOMString 类型的并且所有空格和换行都被显示。

当用户回复此通知以后，回调函数将被调用。

5.1.10 `onshow` 属性, Function类型

若onshow 被赋值给某个回调函数（此时onshow属性值不为null且指向合法的函数），则每当 widget 的状态从可见变为隐藏时会调用回调函数。

注意若可见的widget获得焦点，则 onshow 不应该被调用。

5.1.11 `onhide` 属性, Function类型

若onhide 被赋值给某个回调函数（此时onshow属性值不为null且指向合法的函数），则每当 widget 的状态从可见变为隐藏时会调用回调函数。

注意若可见的widget失去焦点，则 onhide 不应该被调用。

5.1.12 `show`() 方法

show() 方法没有参数也不返回值。调用此函数的作用是显示以前被隐藏的 widget 。如果此 widget 以前就是显示的，则此函数不产生任何效果。

5.1.13 `hide`() 方法

hide() 方法没有参数也不返回值。调用此函数的作用是隐藏以前被显示的 widget 。如果此 widget 以前就是隐藏的，则此函数不产生任何效果。

5.2 `widgetWindow` 接口

Widget 的初始尺寸受 config.xml 文件中的 width 和 height 元素控制。除此之外，可以通过 JavaScript 调用以下方法，动态的改变 widget 大小。

interface widgetWindow {
  
           attribute DOMString status;
           attribute DOMString defaultStatus;
  
      void moveTo(in Integer pos_x, in Integer pos_y);
      void moveBy(in Integer delta_pos_x, in Integer delta_pos_y);
      void resizeTo(in Integer x_size, in Integer y_size);
      void resizeBy(in Integer delta_x_size, in Integer delta_y_size);
    }

5.2.1 `status` 属性, DOMString 类型

status 属性用于在预览 widget 或者管理 widget 页面中显示 widget 状态信息。它被用于向用户显示简短文字信息。比如股票 stock 收报器 widget 可以交替显示最新的股票值和状态信息。

被设置后的 status
信息被保存，直至改变状态信息或置其为空字符串。

5.2.2 `defaultStatus` 属性, DOMString 类型

defaultStatus
属性，若被设置其用处是提供可在预览 widget 或者管理 widget 页面中显示的默认状态信息。

若此属性值非空，删除
window.status 的动作会用 defaultStatus 属性的值代替系统提供的信息。若此值为 null 或为空字符串，widget 运行环境会使用系统提供的信息。

5.2.3 `moveTo`() 方法

若 widget 的位置能被改变，使用 moveTo() 方法可以设置 widget 的位置。此方法有两个参数，pos_x 和 pos_y，分别代表坐标系统的 x 和 y 坐标。坐标系统以视图左上角为原点(0,0)—— x 坐标值向右逐渐增加，y 坐标值向下逐渐增加。

5.2.4 `moveBy`() 方法

若 widget 的位置能被改变，使用 moveBy() 方法可以沿 x/y 方向移动 widget。其参数为整数值的 delta_pos_x 和 delta_pos_y，分别代表要移动的距离。坐标系统以视图左上角为原点(0,0)—— x 坐标值向右逐渐增加，y 坐标值向下逐渐增加。上述两个参数可以是负数，表示向左或者向上移动。

5.2.5 `resizeTo`() 方法

若 widget 的大小能被改变，使用 resizeTo() 方法可以设置 widget 的新的大小。其参数为整数值的 size_x 和 size_y ，表示新的长度和宽度。通过 resizeTo() 设置 widget 大小必须与在 config.xml中设置 width 和 height 元素产生同样效果。size_x
和size_y 参数值都必须大于 1，并且若 resizeTo() 的参数小于1，此函数应不产生任何效果。

5.2.6 `resizeBy`() 方法

resizeBy() 方法改变 widget 大小。其参数为 delta_x_size 和 delta_y_size。此函数将把 widget 宽度增加 delta_x_size，并把 widget 高度增加 delta_y_size，单位是像素。通过 resizeBy() 设置 widget 大小必须与在 config.xml 中设置 width 和 height 元素产生同样效果。这两个参数都可以使用负数，只要保证计算后的结果大于 1×1 像素。若小于此限制，此函数不应该产生任何效果。

5.2.7 存储几何信息

使用上述2个方法改变了 widget 的大小后，新的结果将被储存，并将替代 config.xml 中原始设置的大小。

5.3 `WidgetModeChangeEvent`
接口

CSS -o-widget-mode 属性值被改变后，widgetmodechange 事件将被发送至 Widget 对象。当此事件被派发后，发送给事件监听器的事件对象必须包含用于描述当前模式的 widgetMode 属性。此属性值必须为 Widget 接口中提到的若干合法 widgetMode 属性值中的一个。

WidgetModeChangeEvent 事件必须不是 bubble，必须不可以被取消，且必须实现 Event
接口 [DOM3Events]。此事件没有命名空间 (Event.namespaceURI 为
null).

interface WidgetModeChangeEvent : Event {
  readonly attribute DOMString widgetMode;
  void initMediaTypeChangeEvent(in DOMString typeArg,
                                in boolean canBubbleArg,
                                in boolean cancelableArg,
                                in DOMString widgetModeArg);

  // For DOM Level 3 support
  void initMediaTypeChangeEventNS(in DOMString namespaceURI,
                                  in DOMString typeArg,
                                  in boolean canBubbleArg,
                                  in boolean cancelableArg,
}

5.4 `ResolutionEvent` 接口

当 display 对象的高度或者宽度值被改变后，ResolutionEvent 事件将被派发至 widget 对象。此事件不能 bubble，不能被取消且必须实现 Event 接口
[DOM3Events]。此事件没有命名空间( Event.namespaceURI 为 null).

当被派发时，事件对象必须包含两个属性 width 和 height，表示新的可用的 width 和 height。这两个值应该和 Screen 接口的 availWidth 与 availHeight 属性值保持一致。

interface ResolutionEvent : Event {
  readonly attribute int width;
  readonly attribute int height;
  void initMediaTypeChangeEvent(in DOMString typeArg,
                                in boolean canBubbleArg,
                                in boolean cancelableArg,
                                in int widthArg,
                                in int heightArg);

  // For DOM Level 3 support
  void WidgetModeChangeEventNS(in DOMString namespaceURI,
                               in DOMString typeArg,
                               in boolean canBubbleArg,
                               in boolean cancelableArg,
                               in int widthArg,
                               in int heightArg);
}

6. Widget Autodiscovery

6.1 目的

Widget autodiscovery 的用处是当用户载入页面后，通知用户此页包含 widget。能识别 widget 的客户端应该向用户提供发现并安装页面上的 widget 的机制。

6.2 定义

Widget autodiscovery 元素即是一个 [HTML401] 的12.3章节所定义的 link 元素。与其他 link
元素相似，autodiscovery 元素可以出现在 HTML 或 XHTML 文档的 head
元素中，但是不能出现在 body 元素中。下面是 autodiscovery 元素的一个例子：

 <link
    type="application/x-opera-widgets" rel="alternate"
    href="http://widgets.example.com/example.zip" title="An Example
    Widget"
    />

6.3 与
HTML 和 XHTML 的关系

6.3.1 语法继承自 HTML 和 XHTML

当 widget autodiscovery 元素出现在 [HTML401] 或者 [XHTML10]
文档中时，此元素须和其他元素一样遵守语法规则和限制。

6.3.2 Multiple
autodiscovery elements

一个文档可以包含多个 autodiscovery 元素。客户端应该向用户提供安装自动发现的 widget 的选项，按照出现的顺序给出 widget 列表。

若客户端只允许安装一个自动发现的 widget , 则只要用户决定安装 widget，应该选择安装第一个自动发现的 widget。

6.4 必需的属性

6.4.1 type
属性

type 属性是 autodiscovery 元素的必需属性。type 属性的值必须为 Internet Media type，且此 media type 必须为 application/x-opera-widgets.

6.4.2 rel 属性

rel 属性是 autodiscovery元素的必需属性。如 [HTML401] 的 6.12章节所定义的， rel 属性的值是用空格分割的关键字列表。此列表必须出现 alternate 关键字，可以是大写、小写或者大小写混合。

6.4.3 href
属性

href 属性是 autodiscovery 元素的必需属性。其值必须是 widget 的 URI 。此值可以是相对 URI：此时客户端必须使用文档的基 URI 来解析此相对URI。URI 必须符合 [RFC3987] 规范。

6.5 可选的属性

6.5.1 title
属性

title 属性是 autodiscovery元素的可选属性。客户端应该理解 title
属性为人类可理解的 widget 标题。客户端可能向用户显示此标题。

致谢

此规范的widget 对象
部分参考了 Apple 的 [Dashboard]
文档。

Widget Autodiscovery 很大部分借鉴了 [AtomAutodiscovery]
规范。

参考文献

[RFC2119]: Key words for use in
RFCs to Indicate Requirement Levels, S. Bradner. IETF, March
1997. RFC2119 is available at http://www.ietf.org/rfc/rfc2119
[ZIP]: .ZIP File Format Specification. PKWare Inc., January 2006 The
.ZIP File Format Specification is available at
http://www.pkware.com/business_and_developers/developer/popups/appnote.txt
[XML10]: Extensible Markup
Language (XML) 1.0 (Third Edition). Tim Bray, Jean Paoli, C.
M. Sperberg-McQueen, Eve Maler, François Yergeau. W3C, February
2004. Extensible Markup Language (XML) 1.0 specifciation is available at
http://www.w3.org/TR/REC-xml/
[CSS21]: Cascading Style Sheets,
level 2 revision 1; CSS 2.1 Specification. Bert Bos, Ian
Hickson, Tantek Çelik, Håkon Wium Lie. W3C, April 2006. The
CSS 2.1 Specification can be found at http://www.w3.org/TR/CSS21/
[RFC3987]: Internationalized
Resource Identifiers (IRIs) . M. Duerst, M. Suignard. IETF,
January 2005. RFC3987 is available at http://www.ietf.org/rfc/rfc3987
[Dashboard]: Dashboard Reference. Apple Computer, Inc, May 2006. The Apple
Dashboard Reference is available at
http://developer.apple.com/documentation/AppleApplications/Reference/Das...
[HTML401]: HTML 4.01
Specification, Dave Raggett, Arnaud Le Hors, Ian Jacobs. W3C,
December 1999. The HTML 4.01 Specification is available at
http://www.w3.org/TR/html401/
[XHTML1]: XHTML™ 1.0 The
Extensible HyperText Markup Language (Second Edition), S.
Pemberton et al. W3C, January 2000. The XHTML 1.0 specification is
available at http://www.w3.org/TR/xhtml1/
[AtomAutodiscovery]: Atom Autodiscovery (draft), M. Pilgrim, P. Ringnalda. ATOMPUB
Working Group, May 2005-. The Atom Autodiscovery specification draft is
available at
http://philringnalda.com/rfc/draft-ietf-atompub-autodiscovery-01.html
[SVG]: Scalable Vector Graphics
(SVG) 1.1 Specification, Jon Ferraiolo, 藤沢淳 (FUJISAWA
Jun), Dean Jackson. W3C. The SVG 1.1 specification is available at
http://www.w3.org/TR/SVG/

附录 A: Widget positioning and
sizing

此附录提供确定 widget 大小和位置的算法。这些算法可用于为窗口管理器提供初始 widget 大小，或用于需要区分 widget "viewport size" 和 "widget size" 的平台。

6.6 确定 widget 初始大小的算法

以下算法被用于决定 widget 的起始大小：

打开 config.xml 文件
读取 widget 元素的 'defaultmode' 属性
若 widget 以前被运行过，并且 defaultmode 值为 'widget'，则读取储存的 'start width' 和 'start height' ，跳转到第11步
若 widget 以前被运行过，并且 defaultmode 值为 'application'
，且储存的 'start width' 值超过可使用的渲染区域宽度(换句话说，渲染区域的大小被改变了)，把 'start width' 设置为等于可使用的渲染区域宽度，并继续执行下一步。
若 widget 以前被运行过，并且 defaultmode 值为 'application'
，且储存的 'start height' 值超过可使用的渲染区域高度(换句话说，渲染区域的大小被改变了)，把 'start height' 设置为等于可使用的渲染区域高度，并跳转到第11步。
若 defaultmode 值为 'fullscreen'，且 widget 支持 fullscreen 模式，则把 'start width'
和 'start height' 值设置为可使用的渲染区域的最大宽和高，然后转到第11步。
若 defaultmode 值为 'fullscreen'，但运行环境不支持 'fullscreen' 模式却支持 'application' 模式，则假设 defaultmode 为 'application' 并跳转到第 8步。
若 defaultmode 值为'application'，但运行环境不支持 'fullscreen' 模式却支持 'fullscreen' 模式，则假设 defaultmode 为 'application' 并跳转到第 5步。
若 defaultmode 值为 'application'且平台支持此模式，并允许 widget 自己设置大小：
1. 从 config.xml 中读取 'width' 元素。如果此值小于当前可用的宽度，则存储此值为 'start width'。
2. 若 'width' 值大于当前可用的宽度，则申请最大可用宽度，并储存为 'start width'。
3. 从 config.xml 中读取 'height' 元素。如果此值小于当前可用的高度，则存储此值为 'start height'。
4. 若 'height' 值大于当前可用的宽度，则申请最大可用高度，并储存为 'start height'。
5. 跳转到第 11步。.
若 defaultmode 值为 'application' 或 'fullscreen' 中的一个，但运行平台不支持此两种模式，假设 defaultmode 为 'widget' 并跳转到第 10步。
若 application mode 为 'widget' 且运行平台支持此模式，则使用 config.xml 的 'width' 和 'height' 元素的值作为
'start width' 及 'start height'，并跳转至第10步。
用下面的算法确定 widget 的初始算法。使用 'start width' 及 'start
height'作为初始宽度和初始高度创建 widget 窗口，并启动 widget。永久保存 'start width' 和 'start height' 值。

6.7 确定 widget 初始位置

使用下面的算法确定 widget 的初始位置：

若 widget 以前被运行过，跳转到第4步。
使用 'start_x' 和 'start_y'值，确定 widget 的初始位置。
若 defaultmode 值为'widget'，用以下方法确定初始位置：
1. 读取6.6所示算法确定的 'start width' 值。
2. 若 'start width' 值小于可用宽度，则使用下面公式计算 'start_x' ：start_x = (可用宽度 - start width)/2；否则设置
  start_x 值为 0。
3. 读取6.6所示算法确定的 'start height' 值。
4. 若 'start height' 值小于可用高度，则使用下面公式计算 start_y ：start_y = (可用高度 - start height)/2；否则设置
  start_y 值为 0。
以 start_x 和 start_y 值作为初始位置显示 widget.。

6.8 其他

下面是关于改变 widget 大小和位置的一些建议;这些算法只是介绍性的。

某些窗口管理器支持 'maximized' 和
'restored/unmaximized'状态，此时 'fullscreen' 模式等价于
'maximized' 模式， 'application' 模式等价于'restored/unmaximized'
模式。
在使用 windows.move(To|By) 移动 widget或者使用 windows.resize(To|By)改变 widget 大小后，'start width',
'start height', 'start_x', 和 'start_y' 应该使用新的数值。这些值应该被保存且在下一次启动 widget 时被使用。
使用 'widget' 模式的 widget 必须遵守 widget 本身大小。
当 widget 使用 application 或 fullscreen 模式，widget
运行环境可能忽略计算的 widget 位置和大小信息。

6.9 Virtual viewport resizing

有些窗口管理器不允许 chromeless 窗口被拖动，这给用户留下很小的空间用于移动 widget 。此章节介绍一个减轻此问题的算法。为了给用户提供好的体验，在这些平台上应该实现此类算法。

与 width
元素的关系

注意 width 元素表示画布宽度而不是窗口宽度。在大多数情况下，画布宽度和窗口宽度应该相同，但是有些平台可以通过一下算法使得两者不相同：

若窗口管理器不允许 chromeless 窗口被拖动， Opera 可以通过如下算法改变窗口大小：
1. 搜索 widget 的最左边的边。若此边只含有透明像素，将 width 减一。
2. 搜索 widget 的最右边的边。若此边只含有透明像素，将 width 减一。
3. 重复 1) 和 2) ，直到找到第一个非透明像素
新计算的窗口宽度在任何情况下都不能引起可见像素被剪除。

与 `height` 元素的关系

注意 height 元素表示画布宽度而不是窗口宽度。在大多数情况下，画布高度和窗口高度应该相同，但是有些平台可以通过一下算法使得两者不相同：

若窗口管理器不允许 chromeless 窗口被拖动， Opera 可以通过如下算法改变窗口大小：
1. 搜索 widget 的最顶部的边。若此边只含有透明像素，将 height 减一。
2. 搜索 widget 的最底部的边。若此边只含有透明像素，将 height 减一。
3. 重复 1) 和 2) ，直到找到第一个非透明像素
新计算的窗口高度在任何情况下都不能引起可见像素被剪除。

Opera Widget 规范 1.0 第三版

摘要

本文的地位

目录

1. 引言

1.1 Conformance Requirements

2. Widget 封装

2.1 文件格式

2.2 Widget 文件

2.3 Widget 文件夹结构

2.4 Content-Type

2.5 文件扩展名

3. Widget 配置文件：config.xml

3.1 空格

3.2 widget 元素

3.2.1 widget 元素的可选属性

3.3 <widget>元素必需的子元素

3.3.1 widgetname 元素

3.3.2 width 元素

3.3.3 The height element

3.4 <widget>的可选子元素

3.4.1 widgetfile 元素

3.4.2 author 元素

3.4.2.1. name 元素

3.4.2.2. organization 元素

3.4.2.3. email 元素

3.4.2.4. link 元素

3.4.3 description 元素

3.4.4 icon 元素

3.4.5 security 元素

3.4.5.1. access 元素

3.4.5.2. content 元素

3.4.5.3. 安全模型

3.4.5.4. Intranet 的定义