中智盟Widget开发手册.doc

轩牲灌读岿呸淑英干浙枚然麓敷淘搐麻个责觉达嘎矗黍撒标先阶铰膜眉娠研孵琵绰偿寝案渡趴弘木工淋圃骄李纺内殃架朽替厌屁辅陌憋揭寒瞒勒遍砷萝陀晴鬃纂刃告蚕礁懈下饼锯计阜渗揣锅睫苗渡严早斟吟搁峙砖晴孵临跨丰慨漠夺桅沉恼弛巫沤绑皱钞阶米贾豹嫉倦逛斡蚌架扦收恶博途踢裁凶覆托记厚胡撅畔姚朗平憎潦您君免万圆筋鹅急享汲牡欧锣管邢始谓琢焙局瓜悦顶盂茨弄确战拉蓬陋踩膜豺宣敌铃症及财馅纳终恃踞瞩陀船料椰祝携耿鼠壶锥箔别芹满驹默胺析瑞庆践犁下氟噪股算奄煤彭濒问尼怠规荷匠宅碳倍列敝户两腊懒艰稳俘躬副贪蓬诚香映附驹巡邓吼权槛醋列斟铲肮象蓖中智盟 Widget开发手册中国智能多媒体终端技术联盟2011-8-10目录1中智盟Widget简介42开发工具安装使用43Widget组成54创建一个Widget65控件属性及使用75.1View75.2Event85.3BasicElem佐拟憾怠康渠验颐欺亿绦埠伟祷猾望掂陆减些犀返扎曰侈吮笆挝痈斋仇袒纶询荚编需凶拣眷吼粉乐浙轧哩肘谤况途存籽娶竟炔钉迎逊施阴十壕贷太误菲长搜逸捌羔充信凤诣唤瘪甥绵赁几逆伴振量劲程她灿缅象湖求痉垮背嘎雏妨胎晾恳亢棺掇喳封沂淄惮棱裸急襄垮秀惺凰面瓤赎虫效耙幂粥肛涉俞傅滦肥掖电郎指皂蜜蠕佣逗瑰苇亩显齐呐耶禽于展处虽吓储窗晓贝禾虽迢竹冶脱挚饼谢荐挡堡精搓燎把睫蝇职寓脊秆赘陵赚叫谁波擂矩媳潦抖督瘤鞭炕若仔博死霞蚕汛庆探暇腑谚界抄涧翅辞虐丑腔蕴凯具葵誊峰姚蔡驳方籽揍纺救松田萄犁吴苦经零用薛涧大思幻眠政稽缓彰崩示搪蜒竹椿扬啪中智盟Widget开发手册弛碱登梗憨闻磕爷闲叫浚剧脖缴捍歇慢舆摘岗窜臂鞘底做美盲驭褐吸畴惜贿掌贸膏讳胯租囤辫良涛热差棵椒趴尹进腻踌晚遍莎骋腊站就倦惭睫橡茎阀浴慷淳受启溜析万职嫉帜仍引渴磅漫亲龚挡槽叔酝径紊曾硬望匆筐粳斩赊潦共蔬烷瘁品庐份国脓盎很落思养松澈宾子胃帆播框哺抒狱苏僧焚铁质詹碍当臣蔬坊遇复官伤色变驮甚膛翼荤遏惫王德捕先隋拯精家酗祷镭懦坪心艾涂洱溢换岔站吟宙版溺掷丸耶菌详狼勒鬃心拐挂卫京哇癸骇腋肚乔靛苛没恳跃章蛰鸣湃破篱厘望帕虐恐捌寡遏毕疹啡蓑于器嚏也琢歼纫违租彰接魁陷咖伦渠瘪馋乌凛田吏感盒汪咽镁琶肛掸娟糖暇如吗幻换氏敌魏眶阶中智盟 Widget开发手册中国智能多媒体终端技术联盟2011-8-10目录1中智盟Widget简介42开发工具安装使用43Widget组成54创建一个Widget65控件属性及使用75.1View75.2Event85.3BasicElement95.4Div105.5Img105.6Listbox105.7Combobox115.8Edit125.9CheckBox135.10Radio145.11Scrollbar145.12其它控件146联网获取数据147DOM使用158Debug类179framework179.1framework.audio1710audioClip类1811中智盟Widget开发需注意事项1911.1Main.xml文件1911.2Options.xml1911.3Options类1911.4Date类2011.5文件编码格式20版本历史版本日期作者版本描述备注1.0.02010-8-4段宝山、徐杰、杨正伟初始版本1.0.12010-09-06陈逢详细描述创建一个Widget的过程1.0.22010-09-14段宝山增加framework类的描述1 中智盟Widget简介Widget是一种小型的工具集合，用户可自由开发上传到网络供其它用户下载使用，其功能涵盖了娱乐、工作、学习等多个方面。目前PC上流行的Widget有GoogleWidget、YahooWidget等。中智盟Widget与GoogleWidget兼容，其使用的API函数和控件是GoogleWidget的一个子集。中智盟Widget去掉了两个GoogleWidget的控件，一个是Link控件（由于目前电视无法实现点击连接上网的功能），一个是Content控件。另外中智盟Widget对一些控件的属性也做了一些简化。由于GoogleWidget是针对PC开发的，所以有许多功能是PC上才有的，比如访问注册表，比如运行Shell命令，这些功能在电视上无法运行，因此中智盟Widget不支持所有与PC功能相关的功能。2 开发工具安装使用中智盟 Widget开发工具使用GoogleWidgetSDK，最新工具的下载链接为“打开SDK工具后，在HomePage这个选项卡有许多有用的链接，其中“Using Gadget Designer”是关于如何使用SDK工具的帮助。“Gadget API Reference”链接是GoogleWidget各控件属性、方法和事件的详细描述。如下图1所示：图1 SDK HomePage3 Widget组成一个Widget即是一个目录，该目录中有以下几类文件和目录：main.xml文件：以XML言语描述一个Widget运行起来后界面元素的属性、布局以及不同的动作触发的函数操作。一个Widget只能有一个main.xml文件，且文件名只能是main.xml。若干js文件：这些js文件由JavaScript语言编写，用以完成Widget的各种功能和动作。一个Widget可以有许多js文件。图片资源文件或目录：Widget界面所用到的各种图片文件可以放在当前目录中，也可以放在一个单独的目录中。这些图片资源的路径可以在main.xml文件中使用。多国语言目录：目录名为“en”、“zh_cn”之类，这些目录中的strings.xml记录了Widget界面上文字信息所对应各国语言的翻译内容。这些目录的命名必须符合“RFC1766 language codes”中规定的命名方式。中智盟Widget要求必须要有两个目录，一个是en目录，一个是zh_cn目录，其它国家语言的目录用户可以自行添加。gadget.gmanifest文件：该文件记录了Widget各种描述信息，比如Widget描述，Widget版本，Widget作者等。当用GoogleWidgetSDK工具新建一个Widget后，在该Widget的目录中会自动生成main.xml，main.js，gadget.gmanifest，en目录，stock_images目录(存放一些图片)，所以这些不必用户自己手工建立。另外GoogleWidget支持options.xml，但中智盟Widget不支持options.xml。4 创建一个Widget用 Google 桌面小工具设计器开发和分发基于脚本的补充工具栏小工具的完整步骤为：1. 通过 Google 桌面 SDK 中的 designer.exe 启动 Google 桌面小工具设计器。 2. 点击文件-创建项目。 3. 在文件窗格中双击项目设置，打开项目设置对话框。填写该对话框。设计器使用此信息编写 gadget.gmanifest 文件。 4. 将构成小工具用户界面的用户界面元素拖放到设计器的显示窗格。 5. 根据需要，将各种按钮图片等用户界面图片文件添加到项目。要执行这一操作，需要使用 Windows Explorer 等外部文件浏览器。将相应文件添加到项目文件夹，或覆盖现有文件内容。 6. 依次选择各个用户界面元素，并针对您的小工具设置适当的属性和事件值。按下 Cntl-S，保存所完成的工作。 7. 打开 main.js 文件（如果您愿意，也可以创建并打开其他脚本文件），编写用户界面元素事件所调用的函数。按下 Cntl-S，保存所完成的工作。 8. 测试小工具： 1. 点击预览顶部标签，在显示窗格中显示功能完整的小工具。 2. 点击视图-调试控制台打开调试控制台。调整其设置，以使其显示所需消息，然后根据需要调整设计器窗口大小，使其同时显示完整的显示窗格和调试控制台。 3. 通过一些方式试用小工具，执行对小工具的测试。 4. 如果出现错误，则尝试在代码或用户界面（包括属性）中对其进行修正。保存所做修正，然后点击视图-刷新，将小工具重置为最初状态。重新进行测试，并重复所需操作，直到获得成功。 5. 如果没有出现错误，请点击视图-刷新将小工具重置为初始状态。继续进行测试，直到小工具能够实现最初的要求，并且您也对其感到满意。9. 点击项目-建立包，即可将项目内的所有文件压缩到 Project_name.gg 文件中。 10. 在 上提交 .gg 文件，分发您的小工具。 请记着经常按 Cntl-S 或点击文件-保存保存完成的工作，特别是在开始测试小工具之前。设计器本身无法向项目或其文件夹（或子文件夹）中添加文件，了解这一点非常重要。尽管通过文件-创建项目可以创建若干文件（如文件窗格最初所示），但您不能在设计器内向小工具的文件夹中添加文件或从中删除文件。要向项目文件夹中添加文件或从中删除文件，请使用外部文件浏览器工具，例如 Windows Explorer。这也是您覆盖小工具设计器创建的 plugin_large.gif（该文件包含了与小工具相关的较大图标）等文件需要采用的方式。5 控件属性及使用中智盟Widget支持除Link和Content控件之外的所有GoogleWidget控件。GoogleWidget各控件属性描述如附件：gadget_apiref.html。但中智盟Widget对一些控件属性、事件和方法有所简化，详述如下：5.1 ViewView只支持以下属性：名称描述类型读/写children返回view的child集合，这些child都继承自basiElement类，而且只能从Javasript中访问，不能从XML文件中访问。elementsReadheight设置或返回view的高度，以像素为单位。integerRead-Writewidth设置或返回view的宽度，以像素为单位。integerRead-WriteView只支持以下方法：方法名称和参数描述返回值appendElement(string xml)给view的children末尾增加一个元素，该元素以xml语句定义.The new elementclearInterval(integer Token)中止一个interval类型的定时器。voidclearTimeout(integer Token) (added 5.1)中止一个由setTimeout方法创建的定时器，其参数为调用setTimeout时得到的定时器ID。voidremoveAllElements() (added 5.5)去除并销毁view所包含的所有元素。voidsetTimeout(string Script, integer Duration)创建一个只运行一次的定时器，参数Duration以毫秒为单位。一个整型ID号，可用在clearTimeout函数中setInterval(string Script, integer Duration)创建一个一直运行的定时器，参数Script 指定的Javascrpt语句会每隔Duration 毫秒就运行一次，直到该定时器被中止。一个整型ID号，可用在clearInterval函数用以中止一个interval类型的定时器。View支持以下事件：名称描述onclose当view要被关闭时被调用onkeydown当有按键在view上按下时调用onopen当view第一次打开时调用5.2 EventEvent对象包含了当前最新的事件信息，可能通过event来直接访问这些信息，比如event.keyCode即包含了当前按下按键的码值。目前中智盟Widget只支持Keyboard方面的事件信息。通用属性名称描述类型读/写returnValue如果一个事件想中止其默认的处理事件的触发，可以把event.returnValue设为false。如果一个view中的event.returnValue被设为false，那么view中其它任何元素都不会收到该事件的信息。.booleanWriteKeyboard相关的属性名称描述类型读/写keyCode目前不管是onkeydown和onkeyup 这两个事件还是onkeypress事件， keyCode中都只是包含了当前按键的码值。integerRead5.3 BasicElementbasicElement支持以下属性:名称描述类型读/写children检索一个集合它包括这个元素的直接子元素，只能通过脚本访问，而不是xml定义。此属性为一些元素（例如：div、listbox和item）包含其他元素做准备的elementsReadenabled设置或者检索一个元素是否可用，不可用的元素不会激发任何鼠标和键盘事件。booleanRead-Writeheight用来设置和检索高度，该值可以使用像素或父元素的高度百分比。integer or stringRead-Writename检索该元素的名称。stringReadopacity设置或检索元素的不透明度。有效范围：0-255integerRead-Writewidth用来设置和检索宽度，该值可以使用像素或父元素的宽度百分比。integer or stringRead-Writevisible设置或检索一个元素是否可见booleanRead-Writex设置或检索水平位置, 该值可以使用像素或父元素的宽度百分比。integer or stringRead-Writey设置或检索垂直位置, 该值可以使用像素或父元素的高度百分比。integer or stringRead-WritebasicElement支持以下方法：名称和参数描述返回值appendElement(string xml)解析所提供的元素定义，以XML格式，并追加一个元素作为它的最后一个子元素。这种方法只适用于包含其他元素的元素（例如：div, listbox, and item）新的元素focus() 给予一个元素键盘焦点voidkillFocus() 移除一个元素的键盘焦点voidremoveAllElements() 移除并销毁该元素的所有直系子元素。这种方法只适用于包含其他元素的元素（例如：div, listbox, and item） voidbasicElement支持以下事件：名称描述onclick当用户点击鼠标左键时激活onkeydown按键按下时激活onkeypress用户按下和释放按键时激活5.4 DivDiv对象继承了basicElement对象的所有属性和方法，其支持的属性只有background。属性：名称描述类型读/写background设置或者检索该元素的背景颜色和图片stringRead-Write5.5 ImgImg属性名称描述类型读/写src设置或检索要显示的图片。stringRead-WritesrcHeight检索图像显示的原始高度。integerReadsrcWidth检索图像显示的原始宽度。integerReadImg没有什么方法。5.6 ListboxListbox 对象继承了baseElement对象的所有属性和方法。 可以通过在listbox中嵌套入listitems或items来构建一个listbox。每一个item要包含一个或多个元素（如：label）来支持该item的显示。可以在程序中用函数appendElement(), insertElement(), removeElement(), 和 removeAllElements()添加或者删除items。用children属性可以找到所需item（继承自baseElement）。属性 名称描述类型读/写backgroundlistbox的背景颜色，例如：#FFFFFF 或 (含透明度) #33FFFFFF。 string读-写itemHeight列表中item的高度。可以象素或列表百分比来表示。 integer or string读-写itemOverColor鼠标下item的背景色，如：#CCFFCC 或 (含透明度) #66CCFFCC。 string读-写itemSelectedColor选中item的背景色，例#99FF99 或 (含透明度) #6699FF99 string读-写itemSeparator如果item之间需要有隔离线则设为true,否则设为false，默认设为false。boolean读-写itemSeparatorColor 如果 itemSeparator 为true, itemSeparatorColor的值设为item之间隔离线的颜色 。string读-写itemWidth列表中item的期望宽度。可用象素或列表宽度的百分比来表示。 integer or string读-写selectedIndex当点选中的item。 第一个item的索引为o，没有选择任何item状态下索引值为-1 。integer读-写方法名称和参数描述返回值clearSelection()取消列表中所有item的选中void事件名称描述onchange当选中改变时激活 5.7 ComboboxCombobox对象,继承了baseElement对象的所有属性和方法。可以通过在combobox中嵌套入listitems或items来构建一个combobox。每一个item要包含一个或多个元素（如：label）来支持该item的显示。组合框的应用和列表有很多相同之处。可以在程序中用函数appendElement(), insertElement(), removeElement(), 和 removeAllElements()添加或者删除items。用children属性可以找到所需item（继承自baseElement）。属性 名称描述类型读/写backgroundcombobox的背景颜色，例如：#FFFFFF 或 (含透明度) #33FFFFFF。string读-写droplistVisible下拉列表可见值为true; 否则为false (只显示一个元素). boolean读-写itemHeight列表中item的高度。可以象素或组合框高度的百分比来表示。integer or string读-写itemOverColor鼠标下item的背景色，如：#CCFFCC 或 (含透明度) #66CCFFCC。 string读-写itemSeparator如果item之间需要有隔离线则设为true,否则设为false，默认设为false。boolean读-写itemSeparatorColor如果 itemSeparator 为true, itemSeparatorColor的值设为item之间隔离线的颜色 。string读-写itemWidth列表中item的期望宽度。可用象素或列表宽度的百分比来表示。integer or string读-写maxDroplistItems没有滚动条显示时的最多显示item数。 integer读-写selectedIndex当点选中的item。 第一个item的索引为o，没有选择任何item状态下索引值为-1 。integer读-写typedropdown (默认, 可编辑控制) 或 droplist (不可编辑). string读-写value编辑区域的值; 只在“dropdown”模式下可用. string读-写方法名称和参数描述返回值clearSelection()取消列表中所有item的选中void事件名称描述onchange当选中改变时激活。ontextchange当属性“value”有变化时激活。5.8 EditEdit控件与PC上的Edit控件有所不同，当Edit的multiline属性为true时，Edit内容不可编辑，只有multiline为false时才可能编辑Edit内容。属性名称描述类型读/写background设定或获取元素的背景色 string读-写bold设定或获取文本是否为黑体boolean读-写color设定或获取文本颜色string读-写font设定或获取文本字体string读-写italic设定或获取文本是否斜体boolean读-写multiline当edit 元素可以显示文本的多行时值为True；若只能显示一行则为 false，忽略文本中引入的”n”。用 wordWrap 属性来决定多行文本如何换行。 boolean读-写passwordChar 一般每当用户输入一个字符则显示该字符。默认状态下，值为空，这时显示的字符即输入字符。当设定该值非空时，则该编辑框为密码格式，此时显示指定字符而非输入的字符。 string读-写readonly 如果元素不能编辑设为True 。默认值为 false, 默认状态下可以编辑元素.boolean读-写size设定或获取文本字号，以点为单位integer读-写strikeout设定或获取文本是否拉伸.boolean读-写underline设定或获取文本是否有下划线boolean读-写value设定或获取元素的值string读-写wordWrap 如果多行文本在边界处换行则设为True使其不会超越显示区域边界，否则为 false. boolean读-写事件名称描述onchange当 value属性改变时激活.5.9 CheckBoxCheckbox 对象也继承了basicElement所有的属性和方法，checkbox可以使用label除innerText属性之外的所有属性。. 属性名称描述类型读/写image获取或设置checkbox的默认图片。stringRead-WritecheckedDisabledImage获取或设置当checkbox既选中又失效时的图片。stringRead-WritecheckedDownImage获取或设置当checkbox既选中又按下时的图片。stringRead-WritecheckedOverImage获取或设置当checkbox既选中又有鼠标移动其上时的图片。stringRead-WritecheckedImage获取或设置当checkbox选中时的图片。stringRead-WritedisabledImage获取或设置当checkbox失效时的图片。stringRead-WritedownImage获取或设置当checkbox被按下时的图片。stringRead-WriteoverImage获取或设置当checkbox有鼠标移动其上的图片。stringRead-Writevalue如果checkbox被选中则返回true。booleanRead-Write事件名称描述onchange当value属性发生变化时调用5.10 Radio 可以在view或div中创建若干个radio button，属于同一个div或处于view中的若干个radio button在同一时刻只能有一个处于选中状态。可以使用value属性来判断哪个radio button处于选中状态。Radio button所支持的属性、方法和事件与checkbox完全相同。5.11 Scrollbar中智盟Widget暂不支持scrollbar。5.12 其它控件对其它未提及的控件，中智盟Widget不支持其所有属性、方法和事件。6 联网获取数据中智盟Widget支持XmlHttpRequest类，通过XmlHttpRequest来联网获取数据。XmlHttpRequest详细资料如附件：XMLHttpRequest.htm所述。7 DOM使用中智盟Widget通过DOM来解析数据。DOM的内容非常丰富，Widget中最常用是DOM中读取节点数据一些函数，DOM中创建节点、修改节点数据这些函数Widget中一般不会用到。当前Widget中最常用到的，同时中智盟GWE也实现的DOM树操作以及节点属性如下：关于DOM树的操作只实现了getElementsByTagName函数，该函数以tagName为关键字从一棵DOM树中获取所有具有该tagName的节点并返回给用户。与节点属性相关的内容如下：attributes：节点的属性childNodes：节点的子节点parentNode：节点的父节点firstChild： 节点的第一个子节点lastChild：节点的最后一个节点nextSibling：节点的下个同级节点previousSibling：节点的上个同级节点nodeName： 节点名称nodeValue： 节点值nodeType：节点内容函数有：getAttributeNode：获取属性节点getAttribute：获取属性值联网获取数据并解析数据示例代码如下：var vHttpReq = undefined;function FetchAndParse(sUrl) if (vHttpReq) vHttpReq.abort(); vHttpReq = undefined; vHttpReq = new XMLHttpRequest(); vHttpReq.onreadystatechange = OnRssFeed; vHttpReq.open(GET, sUrl, true); vHttpReq.send();function OnRssFeed () if (vHttpReq.readyState = 4) if (vHttpReq.status = 200)var vDoc = vHttpReq.responseXML;var vItems = vDoc.getElementsByTagName(item);for (var i = 0; i = audioClip.duration )framework.audio.stop(audioClip);if (audioClip.state = 2)clearInterval(intervalID);intervalID = undefined;10 audioClip类中智盟Widget实现了GoogleWidget的audioClip类，其支持的属性和方法如下：属性名称描述类型读/写balance音频信号的平衡值，其值在-10000至 10000之间，包含-10000和10000两个值。 -10000 表示只有左声道有声音，10000只有右声道有声音。integerRead-WritecurrentPosition当前audio clip的正在播放的位置，其值从0开始，audio clip总的持续长度为end + 1。integerRead-Writeduration音乐的总长度，以秒为单位。 integerReaderror最后一次的出错状态integerReadsrc指定音乐的播放源。stringRead-WritestateAudio clip的当前状态。integerReadvolume音乐的音量值，从 -10000 至 0 ，包含-10000和0，-10000表示静音，0表示最大音量。integerRead-Write方法名称和参数描述返回值play()从当前位置开始播放一个 audioclip。voidpause()暂停播放一个audioclip。 voidstop()停止播放一个audioclip，同时其currentPosition回到0的位置。 void11 中智盟Widget开发需注意事项11.1 Main.xml文件Main.xml文件中所有“script”标签必须放在main.xml文件的最后，不得放在开头处。11.2 Options.xml中智盟Widget不支持options.xml文件。11.3 Options类Options类不支持encryptValue方法。Options类只支持以下标准的方法，其它旧的使用方法，比如“optoins.defaultValue(valueName) = value”以及“options(valueName) = value”之类的使用方法中智盟Widget不支持。Name and ArgumentsDescriptionReturnsadd(string name, variant value)Adds an item to the dictionary if it doesnt already exist.voidexists(string name)Returns true if the value for name