HisenseWidget开发手册.doc

Hisense Widget开发手册青岛海信股份有限公司2010-8-4第20页 共20页 目录1HisenseWidget简介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 HisenseWidget简介Widget是一种小型的工具集合，用户可自由开发上传到网络供其它用户下载使用，其功能涵盖了娱乐、工作、学习等多个方面。目前PC上流行的Widget有GoogleWidget、YahooWidget等。HisenseWidget与GoogleWidget兼容，其使用的API函数和控件是GoogleWidget的一个子集。HisenseWidget去掉了两个GoogleWidget的控件，一个是Link控件（由于目前电视无法实现点击连接上网的功能），一个是Content控件。另外HisenseWidget对一些控件的属性也做了一些简化。由于GoogleWidget是针对PC开发的，所以有许多功能是PC上才有的，比如访问注册表，比如运行Shell命令，这些功能在电视上无法运行，因此HisenseWidget不支持所有与PC功能相关的功能。2 开发工具安装使用Hisense Widget开发工具使用GoogleWidgetSDK，最新工具的下载链接为“/downloadsdksubmit?hl=zh-CN”。该SDK工具需要GoogleDesktop软件，下载地址为：“/zh/CN/”。先安装GoogleDesktop，安装之后解压GoogleWidgetSDK压缩包，在解压后的目录中tools目录有designer_en.exe可执行文件，运行该文件后即打开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，但HisenseWidget不支持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. 在 /pluginsubmit?hl=zh_CN 上提交 .gg 文件，分发您的小工具。 请记着经常按 Cntl-S 或点击文件-保存保存完成的工作，特别是在开始测试小工具之前。设计器本身无法向项目或其文件夹（或子文件夹）中添加文件，了解这一点非常重要。尽管通过文件-创建项目可以创建若干文件（如文件窗格最初所示），但您不能在设计器内向小工具的文件夹中添加文件或从中删除文件。要向项目文件夹中添加文件或从中删除文件，请使用外部文件浏览器工具，例如 Windows Explorer。这也是您覆盖小工具设计器创建的 plugin_large.gif（该文件包含了与小工具相关的较大图标）等文件需要采用的方式。5 控件属性及使用HisenseWidget支持除Link和Content控件之外的所有GoogleWidget控件。GoogleWidget各控件属性描述如附件：gadget_apiref.html。但HisenseWidget对一些控件属性、事件和方法有所简化，详述如下：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即包含了当前按下按键的码值。目前HisenseWidget只支持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 ScrollbarHisenseWidget暂不支持scrollbar。5.12 其它控件对其它未提及的控件，HisenseWidget不支持其所有属性、方法和事件。6 联网获取数据HisenseWidget支持XmlHttpRequest类，通过XmlHttpRequest来联网获取数据。XmlHttpRequest详细资料如附件：XMLHttpRequest.htm所述。7 DOM使用HisenseWidget通过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类HisenseWidget实现了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”标签必须放在m