中智盟Widget開發(fā)手冊.doc

中智盟 Widget開發(fā)手冊中國智能多媒體終端技術(shù)聯(lián)盟2011-8-10第20頁 共20頁 目錄1中智盟Widget簡介42開發(fā)工具安裝使用43Widget組成54創(chuàng)建一個Widget65控件屬性及使用75.1View75.2Event85.3BasicElement95.4Div105.5Img105.6Listbox105.7Combobox115.8Edit125.9CheckBox135.10Radio145.11Scrollbar145.12其它控件146聯(lián)網(wǎng)獲取數(shù)據(jù)147DOM使用158Debug類179framework179.1framework.audio1710audioClip類1811中智盟Widget開發(fā)需注意事項(xiàng)1911.1Main.xml文件1911.2Options.xml1911.3Options類1911.4Date類2011.5文件編碼格式20版本歷史版本日期作者版本描述備注1.0.02010-8-4段寶山、徐杰、楊正偉初始版本1.0.12010-09-06陳逢詳細(xì)描述創(chuàng)建一個Widget的過程1.0.22010-09-14段寶山增加framework類的描述1 中智盟Widget簡介Widget是一種小型的工具集合，用戶可自由開發(fā)上傳到網(wǎng)絡(luò)供其它用戶下載使用，其功能涵蓋了娛樂、工作、學(xué)習(xí)等多個方面。目前PC上流行的Widget有GoogleWidget、YahooWidget等。中智盟Widget與GoogleWidget兼容，其使用的API函數(shù)和控件是GoogleWidget的一個子集。中智盟Widget去掉了兩個GoogleWidget的控件，一個是Link控件（由于目前電視無法實(shí)現(xiàn)點(diǎn)擊連接上網(wǎng)的功能），一個是Content控件。另外中智盟Widget對一些控件的屬性也做了一些簡化。由于GoogleWidget是針對PC開發(fā)的，所以有許多功能是PC上才有的，比如訪問注冊表，比如運(yùn)行Shell命令，這些功能在電視上無法運(yùn)行，因此中智盟Widget不支持所有與PC功能相關(guān)的功能。2 開發(fā)工具安裝使用中智盟 Widget開發(fā)工具使用GoogleWidgetSDK，最新工具的下載鏈接為“/downloadsdksubmit?hl=zh-CN”。該SDK工具需要GoogleDesktop軟件，下載地址為：“/zh/CN/”。先安裝GoogleDesktop，安裝之后解壓GoogleWidgetSDK壓縮包，在解壓后的目錄中tools目錄有designer_en.exe可執(zhí)行文件，運(yùn)行該文件后即打開GoogleWidgetSDK工具。打開SDK工具后，在HomePage這個選項(xiàng)卡有許多有用的鏈接，其中“Using Gadget Designer”是關(guān)于如何使用SDK工具的幫助?！癎adget API Reference”鏈接是GoogleWidget各控件屬性、方法和事件的詳細(xì)描述。如下圖1所示：圖1 SDK HomePage3 Widget組成一個Widget即是一個目錄，該目錄中有以下幾類文件和目錄：main.xml文件：以XML言語描述一個Widget運(yùn)行起來后界面元素的屬性、布局以及不同的動作觸發(fā)的函數(shù)操作。一個Widget只能有一個main.xml文件，且文件名只能是main.xml。若干js文件：這些js文件由JavaScript語言編寫，用以完成Widget的各種功能和動作。一個Widget可以有許多js文件。圖片資源文件或目錄：Widget界面所用到的各種圖片文件可以放在當(dāng)前目錄中，也可以放在一個單獨(dú)的目錄中。這些圖片資源的路徑可以在main.xml文件中使用。多國語言目錄：目錄名為“en”、“zh_cn”之類，這些目錄中的strings.xml記錄了Widget界面上文字信息所對應(yīng)各國語言的翻譯內(nèi)容。這些目錄的命名必須符合“RFC1766 language codes”中規(guī)定的命名方式。中智盟Widget要求必須要有兩個目錄，一個是en目錄，一個是zh_cn目錄，其它國家語言的目錄用戶可以自行添加。gadget.gmanifest文件：該文件記錄了Widget各種描述信息，比如Widget描述，Widget版本，Widget作者等。當(dāng)用GoogleWidgetSDK工具新建一個Widget后，在該Widget的目錄中會自動生成main.xml，main.js，gadget.gmanifest，en目錄，stock_images目錄(存放一些圖片)，所以這些不必用戶自己手工建立。另外GoogleWidget支持options.xml，但中智盟Widget不支持options.xml。4 創(chuàng)建一個Widget用 Google 桌面小工具設(shè)計(jì)器開發(fā)和分發(fā)基于腳本的補(bǔ)充工具欄小工具的完整步驟為：1. 通過 Google 桌面 SDK 中的 designer.exe 啟動 Google 桌面小工具設(shè)計(jì)器。 2. 點(diǎn)擊文件-創(chuàng)建項(xiàng)目。 3. 在文件窗格中雙擊項(xiàng)目設(shè)置，打開項(xiàng)目設(shè)置對話框。填寫該對話框。設(shè)計(jì)器使用此信息編寫 gadget.gmanifest 文件。 4. 將構(gòu)成小工具用戶界面的用戶界面元素拖放到設(shè)計(jì)器的顯示窗格。 5. 根據(jù)需要，將各種按鈕圖片等用戶界面圖片文件添加到項(xiàng)目。要執(zhí)行這一操作，需要使用 Windows Explorer 等外部文件瀏覽器。將相應(yīng)文件添加到項(xiàng)目文件夾，或覆蓋現(xiàn)有文件內(nèi)容。 6. 依次選擇各個用戶界面元素，并針對您的小工具設(shè)置適當(dāng)?shù)膶傩院褪录?。按?Cntl-S，保存所完成的工作。 7. 打開 main.js 文件（如果您愿意，也可以創(chuàng)建并打開其他腳本文件），編寫用戶界面元素事件所調(diào)用的函數(shù)。按下 Cntl-S，保存所完成的工作。 8. 測試小工具： 1. 點(diǎn)擊預(yù)覽頂部標(biāo)簽，在顯示窗格中顯示功能完整的小工具。 2. 點(diǎn)擊視圖-調(diào)試控制臺打開調(diào)試控制臺。調(diào)整其設(shè)置，以使其顯示所需消息，然后根據(jù)需要調(diào)整設(shè)計(jì)器窗口大小，使其同時顯示完整的顯示窗格和調(diào)試控制臺。 3. 通過一些方式試用小工具，執(zhí)行對小工具的測試。 4. 如果出現(xiàn)錯誤，則嘗試在代碼或用戶界面（包括屬性）中對其進(jìn)行修正。保存所做修正，然后點(diǎn)擊視圖-刷新，將小工具重置為最初狀態(tài)。重新進(jìn)行測試，并重復(fù)所需操作，直到獲得成功。 5. 如果沒有出現(xiàn)錯誤，請點(diǎn)擊視圖-刷新將小工具重置為初始狀態(tài)。繼續(xù)進(jìn)行測試，直到小工具能夠?qū)崿F(xiàn)最初的要求，并且您也對其感到滿意。9. 點(diǎn)擊項(xiàng)目-建立包，即可將項(xiàng)目內(nèi)的所有文件壓縮到 Project_name.gg 文件中。 10. 在 /pluginsubmit?hl=zh_CN 上提交 .gg 文件，分發(fā)您的小工具。 請記著經(jīng)常按 Cntl-S 或點(diǎn)擊文件-保存保存完成的工作，特別是在開始測試小工具之前。設(shè)計(jì)器本身無法向項(xiàng)目或其文件夾（或子文件夾）中添加文件，了解這一點(diǎn)非常重要。盡管通過文件-創(chuàng)建項(xiàng)目可以創(chuàng)建若干文件（如文件窗格最初所示），但您不能在設(shè)計(jì)器內(nèi)向小工具的文件夾中添加文件或從中刪除文件。要向項(xiàng)目文件夾中添加文件或從中刪除文件，請使用外部文件瀏覽器工具，例如 Windows Explorer。這也是您覆蓋小工具設(shè)計(jì)器創(chuàng)建的 plugin_large.gif（該文件包含了與小工具相關(guān)的較大圖標(biāo)）等文件需要采用的方式。5 控件屬性及使用中智盟Widget支持除Link和Content控件之外的所有GoogleWidget控件。GoogleWidget各控件屬性描述如附件：gadget_apiref.html。但中智盟Widget對一些控件屬性、事件和方法有所簡化，詳述如下：5.1 ViewView只支持以下屬性：名稱描述類型讀/寫children返回view的child集合，這些child都繼承自basiElement類，而且只能從Javasript中訪問，不能從XML文件中訪問。elementsReadheight設(shè)置或返回view的高度，以像素為單位。integerRead-Writewidth設(shè)置或返回view的寬度，以像素為單位。integerRead-WriteView只支持以下方法：方法名稱和參數(shù)描述返回值appendElement(string xml)給view的children末尾增加一個元素，該元素以xml語句定義.The new elementclearInterval(integer Token)中止一個interval類型的定時器。voidclearTimeout(integer Token) (added 5.1)中止一個由setTimeout方法創(chuàng)建的定時器，其參數(shù)為調(diào)用setTimeout時得到的定時器ID。voidremoveAllElements() (added 5.5)去除并銷毀view所包含的所有元素。voidsetTimeout(string Script, integer Duration)創(chuàng)建一個只運(yùn)行一次的定時器，參數(shù)Duration以毫秒為單位。一個整型ID號，可用在clearTimeout函數(shù)中setInterval(string Script, integer Duration)創(chuàng)建一個一直運(yùn)行的定時器，參數(shù)Script 指定的Javascrpt語句會每隔Duration 毫秒就運(yùn)行一次，直到該定時器被中止。一個整型ID號，可用在clearInterval函數(shù)用以中止一個interval類型的定時器。View支持以下事件：名稱描述onclose當(dāng)view要被關(guān)閉時被調(diào)用onkeydown當(dāng)有按鍵在view上按下時調(diào)用onopen當(dāng)view第一次打開時調(diào)用5.2 EventEvent對象包含了當(dāng)前最新的事件信息，可能通過event來直接訪問這些信息，比如event.keyCode即包含了當(dāng)前按下按鍵的碼值。目前中智盟Widget只支持Keyboard方面的事件信息。通用屬性名稱描述類型讀/寫returnValue如果一個事件想中止其默認(rèn)的處理事件的觸發(fā)，可以把event.returnValue設(shè)為false。如果一個view中的event.returnValue被設(shè)為false，那么view中其它任何元素都不會收到該事件的信息。.booleanWriteKeyboard相關(guān)的屬性名稱描述類型讀/寫keyCode目前不管是onkeydown和onkeyup 這兩個事件還是onkeypress事件， keyCode中都只是包含了當(dāng)前按鍵的碼值。integerRead5.3 BasicElementbasicElement支持以下屬性:名稱描述類型讀/寫children檢索一個集合它包括這個元素的直接子元素，只能通過腳本訪問，而不是xml定義。此屬性為一些元素（例如：div、listbox和item）包含其他元素做準(zhǔn)備的elementsReadenabled設(shè)置或者檢索一個元素是否可用，不可用的元素不會激發(fā)任何鼠標(biāo)和鍵盤事件。booleanRead-Writeheight用來設(shè)置和檢索高度，該值可以使用像素或父元素的高度百分比。integer or stringRead-Writename檢索該元素的名稱。stringReadopacity設(shè)置或檢索元素的不透明度。有效范圍：0-255integerRead-Writewidth用來設(shè)置和檢索寬度，該值可以使用像素或父元素的寬度百分比。integer or stringRead-Writevisible設(shè)置或檢索一個元素是否可見booleanRead-Writex設(shè)置或檢索水平位置, 該值可以使用像素或父元素的寬度百分比。integer or stringRead-Writey設(shè)置或檢索垂直位置, 該值可以使用像素或父元素的高度百分比。integer or stringRead-WritebasicElement支持以下方法：名稱和參數(shù)描述返回值appendElement(string xml)解析所提供的元素定義，以XML格式，并追加一個元素作為它的最后一個子元素。這種方法只適用于包含其他元素的元素（例如：div, listbox, and item）新的元素focus() 給予一個元素鍵盤焦點(diǎn)voidkillFocus() 移除一個元素的鍵盤焦點(diǎn)voidremoveAllElements() 移除并銷毀該元素的所有直系子元素。這種方法只適用于包含其他元素的元素（例如：div, listbox, and item） voidbasicElement支持以下事件：名稱描述onclick當(dāng)用戶點(diǎn)擊鼠標(biāo)左鍵時激活onkeydown按鍵按下時激活onkeypress用戶按下和釋放按鍵時激活5.4 DivDiv對象繼承了basicElement對象的所有屬性和方法，其支持的屬性只有background。屬性：名稱描述類型讀/寫background設(shè)置或者檢索該元素的背景顏色和圖片stringRead-Write5.5 ImgImg屬性名稱描述類型讀/寫src設(shè)置或檢索要顯示的圖片。stringRead-WritesrcHeight檢索圖像顯示的原始高度。integerReadsrcWidth檢索圖像顯示的原始寬度。integerReadImg沒有什么方法。5.6 ListboxListbox 對象繼承了baseElement對象的所有屬性和方法。 可以通過在listbox中嵌套入listitems或items來構(gòu)建一個listbox。每一個item要包含一個或多個元素（如：label）來支持該item的顯示。可以在程序中用函數(shù)appendElement(), insertElement(), removeElement(), 和 removeAllElements()添加或者刪除items。用children屬性可以找到所需item（繼承自baseElement）。屬性 名稱描述類型讀/寫backgroundlistbox的背景顏色，例如：#FFFFFF 或 (含透明度) #33FFFFFF。 string讀-寫itemHeight列表中item的高度?？梢韵笏鼗蛄斜戆俜直葋肀硎?。 integer or string讀-寫itemOverColor鼠標(biāo)下item的背景色，如：#CCFFCC 或 (含透明度) #66CCFFCC。 string讀-寫itemSelectedColor選中item的背景色，例#99FF99 或 (含透明度) #6699FF99 string讀-寫itemSeparator如果item之間需要有隔離線則設(shè)為true,否則設(shè)為false，默認(rèn)設(shè)為false。boolean讀-寫itemSeparatorColor 如果 itemSeparator 為true, itemSeparatorColor的值設(shè)為item之間隔離線的顏色 。string讀-寫itemWidth列表中item的期望寬度。可用象素或列表寬度的百分比來表示。 integer or string讀-寫selectedIndex當(dāng)點(diǎn)選中的item。 第一個item的索引為o，沒有選擇任何item狀態(tài)下索引值為-1 。integer讀-寫方法名稱和參數(shù)描述返回值clearSelection()取消列表中所有item的選中void事件名稱描述onchange當(dāng)選中改變時激活 5.7 ComboboxCombobox對象,繼承了baseElement對象的所有屬性和方法?？梢酝ㄟ^在combobox中嵌套入listitems或items來構(gòu)建一個combobox。每一個item要包含一個或多個元素（如：label）來支持該item的顯示。組合框的應(yīng)用和列表有很多相同之處?？梢栽诔绦蛑杏煤瘮?shù)appendElement(), insertElement(), removeElement(), 和 removeAllElements()添加或者刪除items。用children屬性可以找到所需item（繼承自baseElement）。屬性 名稱描述類型讀/寫backgroundcombobox的背景顏色，例如：#FFFFFF 或 (含透明度) #33FFFFFF。string讀-寫droplistVisible下拉列表可見值為true; 否則為false (只顯示一個元素). boolean讀-寫itemHeight列表中item的高度?？梢韵笏鼗蚪M合框高度的百分比來表示。integer or string讀-寫itemOverColor鼠標(biāo)下item的背景色，如：#CCFFCC 或 (含透明度) #66CCFFCC。 string讀-寫itemSeparator如果item之間需要有隔離線則設(shè)為true,否則設(shè)為false，默認(rèn)設(shè)為false。boolean讀-寫itemSeparatorColor如果 itemSeparator 為true, itemSeparatorColor的值設(shè)為item之間隔離線的顏色 。string讀-寫itemWidth列表中item的期望寬度?？捎孟笏鼗蛄斜韺挾鹊陌俜直葋肀硎尽nteger or string讀-寫maxDroplistItems沒有滾動條顯示時的最多顯示item數(shù)。 integer讀-寫selectedIndex當(dāng)點(diǎn)選中的item。 第一個item的索引為o，沒有選擇任何item狀態(tài)下索引值為-1 。integer讀-寫typedropdown (默認(rèn), 可編輯控制) 或 droplist (不可編輯). string讀-寫value編輯區(qū)域的值; 只在“dropdown”模式下可用. string讀-寫方法名稱和參數(shù)描述返回值clearSelection()取消列表中所有item的選中void事件名稱描述onchange當(dāng)選中改變時激活。ontextchange當(dāng)屬性“value”有變化時激活。5.8 EditEdit控件與PC上的Edit控件有所不同，當(dāng)Edit的multiline屬性為true時，Edit內(nèi)容不可編輯，只有multiline為false時才可能編輯Edit內(nèi)容。屬性名稱描述類型讀/寫background設(shè)定或獲取元素的背景色 string讀-寫bold設(shè)定或獲取文本是否為黑體boolean讀-寫color設(shè)定或獲取文本顏色string讀-寫font設(shè)定或獲取文本字體string讀-寫italic設(shè)定或獲取文本是否斜體boolean讀-寫multiline當(dāng)edit 元素可以顯示文本的多行時值為True；若只能顯示一行則為 false，忽略文本中引入的”n”。用 wordWrap 屬性來決定多行文本如何換行。 boolean讀-寫passwordChar 一般每當(dāng)用戶輸入一個字符則顯示該字符。默認(rèn)狀態(tài)下，值為空，這時顯示的字符即輸入字符。當(dāng)設(shè)定該值非空時，則該編輯框?yàn)槊艽a格式，此時顯示指定字符而非輸入的字符。 string讀-寫readonly 如果元素不能編輯設(shè)為True 。默認(rèn)值為 false, 默認(rèn)狀態(tài)下可以編輯元素.boolean讀-寫size設(shè)定或獲取文本字號，以點(diǎn)為單位integer讀-寫strikeout設(shè)定或獲取文本是否拉伸.boolean讀-寫underline設(shè)定或獲取文本是否有下劃線boolean讀-寫value設(shè)定或獲取元素的值string讀-寫wordWrap 如果多行文本在邊界處換行則設(shè)為True使其不會超越顯示區(qū)域邊界，否則為 false. boolean讀-寫事件名稱描述onchange當(dāng) value屬性改變時激活.5.9 CheckBoxCheckbox 對象也繼承了basicElement所有的屬性和方法，checkbox可以使用label除innerText屬性之外的所有屬性。. 屬性名稱描述類型讀/寫image獲取或設(shè)置checkbox的默認(rèn)圖片。stringRead-WritecheckedDisabledImage獲取或設(shè)置當(dāng)checkbox既選中又失效時的圖片。stringRead-WritecheckedDownImage獲取或設(shè)置當(dāng)checkbox既選中又按下時的圖片。stringRead-WritecheckedOverImage獲取或設(shè)置當(dāng)checkbox既選中又有鼠標(biāo)移動其上時的圖片。stringRead-WritecheckedImage獲取或設(shè)置當(dāng)checkbox選中時的圖片。stringRead-WritedisabledImage獲取或設(shè)置當(dāng)checkbox失效時的圖片。stringRead-WritedownImage獲取或設(shè)置當(dāng)checkbox被按下時的圖片。stringRead-WriteoverImage獲取或設(shè)置當(dāng)checkbox有鼠標(biāo)移動其上的圖片。stringRead-Writevalue如果checkbox被選中則返回true。booleanRead-Write事件名稱描述onchange當(dāng)value屬性發(fā)生變化時調(diào)用5.10 Radio 可以在view或div中創(chuàng)建若干個radio button，屬于同一個div或處于view中的若干個radio button在同一時刻只能有一個處于選中狀態(tài)?？梢允褂胿alue屬性來判斷哪個radio button處于選中狀態(tài)。Radio button所支持的屬性、方法和事件與checkbox完全相同。5.11 Scrollbar中智盟Widget暫不支持scrollbar。5.12 其它控件對其它未提及的控件，中智盟Widget不支持其所有屬性、方法和事件。6 聯(lián)網(wǎng)獲取數(shù)據(jù)中智盟Widget支持XmlHttpRequest類，通過XmlHttpRequest來聯(lián)網(wǎng)獲取數(shù)據(jù)。XmlHttpRequest詳細(xì)資料如附件：XMLHttpRequest.htm所述。7 DOM使用中智盟Widget通過DOM來解析數(shù)據(jù)。DOM的內(nèi)容非常豐富，Widget中最常用是DOM中讀取節(jié)點(diǎn)數(shù)據(jù)一些函數(shù)，DOM中創(chuàng)建節(jié)點(diǎn)、修改節(jié)點(diǎn)數(shù)據(jù)這些函數(shù)Widget中一般不會用到。當(dāng)前Widget中最常用到的，同時中智盟GWE也實(shí)現(xiàn)的DOM樹操作以及節(jié)點(diǎn)屬性如下：關(guān)于DOM樹的操作只實(shí)現(xiàn)了getElementsByTagName函數(shù)，該函數(shù)以tagName為關(guān)鍵字從一棵DOM樹中獲取所有具有該tagName的節(jié)點(diǎn)并返回給用戶。與節(jié)點(diǎn)屬性相關(guān)的內(nèi)容如下：attributes：節(jié)點(diǎn)的屬性childNodes：節(jié)點(diǎn)的子節(jié)點(diǎn)parentNode：節(jié)點(diǎn)的父節(jié)點(diǎn)firstChild： 節(jié)點(diǎn)的第一個子節(jié)點(diǎn)lastChild：節(jié)點(diǎn)的最后一個節(jié)點(diǎn)nextSibling：節(jié)點(diǎn)的下個同級節(jié)點(diǎn)previousSibling：節(jié)點(diǎn)的上個同級節(jié)點(diǎn)nodeName： 節(jié)點(diǎn)名稱nodeValue： 節(jié)點(diǎn)值nodeType：節(jié)點(diǎn)內(nèi)容函數(shù)有：getAttributeNode：獲取屬性節(jié)點(diǎn)getAttribute：獲取屬性值聯(lián)網(wǎng)獲取數(shù)據(jù)并解析數(shù)據(jù)示例代碼如下：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實(shí)現(xiàn)了GoogleWidget的audioClip類，其支持的屬性和方法如下：屬性名稱描述類型讀/寫balance音頻信號的平衡值，其值在-10000至 10000之間，包含-10000和10000兩個值。 -10000 表示只有左聲道有聲音，10000只有右聲道有聲音。integerRead-WritecurrentPosition當(dāng)前audio clip的正在播放的位置，其值從0開始，audio clip總的持續(xù)長度為end + 1。integerRead-Writeduration音樂的總長度，以秒為單位。 integerReaderror最后一次的出錯狀態(tài)integerReadsrc指定音樂的播放源。stringRead-WritestateAudio clip的當(dāng)前狀態(tài)。integerReadvolume音樂的音量值，從 -10000 至 0 ，包含-10000和0，-10000表示靜音，0表示最大音量。integerRead-Write方法名稱和參數(shù)描述返回值play()從當(dāng)前位置開始播放一個 audioclip。voidpause()暫停播放一個audioclip。 voidstop()停止播放一個audioclip，同時其currentPosition回到0的位置。 void11 中智盟Widget開發(fā)需注意事項(xiàng)11.1 Main.xml文件Main.xml文件中所有“script”標(biāo)簽