您的第一個 Widget：Hello World! Widget

▲前頁 ☆目次 ▼次頁
下載 Hello World 範例檔案

您將學到什麼？

本節範例提供您如何製作一個最簡單的 Yahoo! Widget Engine（YWE）的 widget 小程式 － Hello World。您將會學到：

  • 架構最基本的 .kon XML 的檔案
  • 如何利用 YWE 環境進行 widget 測試與除錯
  • 如何加入互動性
  • 構成 YWE widget

這個範例就像上圖一樣，會在 widget 視窗中間顯示兩行字。第一行字是使用粗體 + 斜體的新細明體來顯示，而第二行字是使用粗體的新細明體來顯示。當滑鼠指標在第二行字的上面時，便會反白，如果此時按下滑鼠按鍵，便會連到 Yahoo! 奇摩首頁。

我們將以這些功能做為這個 Hello World widget 的目標，利用 Windows 平台上的 NotePad++ 編輯器來製作這個範例，一步步地解說如何架構一個最簡單的 YWE widget。

▲Top

架構最基本的 .kon XML 的檔案

YWE Widget 最重要的檔案就是 .kon 檔，該檔案事實上是個 XML 格式的檔案。我們來看一下一般 XML 碼的語法為何：

程式列表 1

<tag>
	<subtag attr="value1">
	</subtag>
</tag>

可以看到，都是巢狀式的 <tag></tag>，以 <tag> 起始，以 </tag> 結束，在兩者間可以在放更多這樣的組合。而 tag 後面可以接屬性，例如 <subtag attr="value1"> 這行，您可以看到 subtag 有一個屬性叫 attr，其數值為 value1 字串。一般 XML 都是以此類推，這邊就不再多做解釋。

有了這樣 XML 的概念，我們可以先再往下看 Yahoo! Widget Engine 的 XML 語法。

以這個 Hello World! 範例為例，最基本的 XML 碼如下：

程式列表 2

<widget>	1
	<window title="Hello World!">	2
		<name>hello</name>	3
		<width>400</width>	4
		<height>300</height>
		<image src="Resources/background.png"/>	5
		<text name="helloText">	6
			<data>第一個 Widget - Hello World!</data>	7
			<font>新細明體</font>	8
			<color>#FFFFFF</color>	9
			<style>bold;italic</style>	10
			<size>18</size>	11
			<hOffset>95</hOffset>	12
			<vOffset>120</vOffset>
		</text>
	</window>
</widget>

一一來看這些 XML tag 的意義：

1 <widget>
這是 YWE widget 裡最基本的 XML tag，在 與 兩個起始與結束 tag 之間，我們可以設定 widget 的所有視窗、屬性、圖形、文字、函式、動作、事件等。
2 <window title="Hello World!">
這行宣告這個 widget 有個視窗，其視窗抬頭為 Hello World!。其中視窗抬頭就是 title 這個屬性，其值就是視窗抬頭。而在此行至 </window> 之間的所有 XML 碼皆為該視窗的宣告。
3 <name>hello</name>
name 這個 tag 的主要意義是在宣告這個視窗往後的 JavaScript 程式來說，我們如何可以存取並控制這個視窗的所有資料與行為。以此為例，在 JavaScript 如果我們想得知這個視窗的寬度，我們可以這麼寫：alert("這視窗的寬度為" + hello.width)，這樣便會出現一個對話框顯示這個視窗的寬度。請注意，name 這個屬性每個物件都必須是不同的名稱，且不能有空白、小數點（.）或是除了 0-9, A-Z, a-z 之外的字元。其規則限制與 JavaScript 的變數名稱一樣。
4 <width>400</width> 與 <height>300</height>
這是在定義視窗的寬度（width）與高度（height），單位皆為像素。
5 <image src="Resources/background.png"/>
這代表有個圖形，其原始檔案（src）是放在 Resources 目錄下的 background.png。 這個路徑的原則是根據 .kon 檔所在的目錄，再加上 src 屬性的路徑所構成的。所有 .kon 檔所會存取到的檔案路徑都是以此類推。請注意，以 XML 語法來說，如果是單行便可解決的敘述，可以在最後用 /> 結尾，而不需加入 </image> 這樣的結束 tag。
6 <text name="helloText">
從這行到 </text> 之間皆為宣告文字區塊（text）物件的 XML 碼。首先我們定義這個文字區塊的 JavaScript 程式中的名稱為 helloText。
7 <data>最簡單的 Widget - Hello World!</data>
在 <data> 與 </data> 之間的字串即為該文字區塊的顯示內容。
8 <font>新細明體</font>
在 <font> 與 </font> 之間為指定該段文字區塊所使用的顯示字型名稱。您可以宣告如 <font>新細明體, 細明體</font> 這樣的字型宣告方式，這代表萬一系統沒有「新細明體」這個字型，將會用下一個字型「細明體」來替代，以此類推。
9 <color>#FFFFFF</color>
這是宣告顯示該文字區塊的 RGB 顏色為何，兩個十六進位為一組，分別代表 R（紅）、G（綠）、B（藍）的 0-255（0xFF） 數值。以 #FFFFFF 為例，就代表白色。其規則與 HTML 的顏色代碼一樣。
10 <style>bold;italic</style>
這代表該段文字區塊用了粗體（bold）與斜體（italic）作為顯示樣式。如同時使用多種樣式，可以用 ; 作分隔。樣式的特別代碼可以在 YWE Reference Manual 中查到。
11 <size>18</size>
這是指定文字區塊的字級級數。這個範例就是指定 18 點字級。
12 <hOffset>95</hOffset> 與 <vOffset>120</vOffset>
這兩組 tag 是指定這個文字區塊其左上角的水平（hOffset）與垂直（vOffset）位置，都是以像素為單位。

▲Top

如何利用 YWE 環境進行測試與除錯（debug）

Yahoo! Widget Engine 允許您不需將所有檔案打包成 .widget 檔案便可以進行測試。只要您將 .kon 檔案按兩下便可以讓您開發中的 widget 載入 YWE 環境中進行測試。

而 YWE 也內建有除錯的工具，您可以在 <widget> 後一行（第二行）插入如下的 tag 便可打開 debug 視窗：

程式列表 3

<debug>on</debug>

這樣便可啟動 debug 視窗。我們將在 Hands-On 實作部份中有進一步解說。

▲Top

Hello World! 範例實作 Hands-On

1. 只要利用 Windows 內附的「記事本」便可製作 widget 的主要檔案 .kon 檔。但是在本教材中，我們主要以更方便的 XML 編輯器 － Notepad++ 來當做我們編寫 .kon 檔的編輯器。請直接在桌面上的 Notepad++ 圖像上按兩下執行它。

2. 執行後，您會看到一個空白的視窗，請先設定文件編碼格式為 UTF-8（Unicode）。作法是請選擇「格式」功能表下的「編譯成 UTF-8 碼」項目。

3. 再來先設定程式語言為 XML。請選擇「程式語言」功能表下的「XML」項目。

4. 接下來請把剛剛的 Hello World! Widget 的 XML 拷貝貼到空白的 Notepad++ 視窗中。我們強烈建議用打的，會讓各位印象較深。

5. 各位可以看到 Notepad++ 在處理 XML 方面有用顏色及樣式來特別標示，方便您可以看出 XML 的結構及除錯。接下來我們將這個檔案存成 HelloWorld.kon 檔。請按上列工具列磁碟片的按鈕（由左數來第三個），然後選到 HelloWorld 這個檔案夾，鍵入「HelloWorld.kon」，並按下「儲存」按鈕。

6. 回到檔案總管，您會看到 HelloWorld 這個目錄中有個 HelloWorld.kon 檔，請在上面按兩下打開它。之後會出現 YWE 的視窗，問您是否允許執行這個 widget，請按「允許」。之後會出現 widget 的視窗。

以上便是架構一個 YWE widget 最簡單的方法，您可以依照我們上面的 .kon 檔的內容解說試著去改變 .kon 檔的內容來改變文字的顯示方式，甚至加入更多行文字。

接下來我們要告訴您如何啟動及使用 YWE 的除錯輔助功能。

1. 請再回到 Notepad++，在第二行鍵入 <debug>on</debug>，然後將檔案儲存起來。

2. 回到檔案總管，再打開 HelloWorld.kon 檔。之後會出現 YWE 允許或拒絕執行 widget 的詢問視窗，請按「允許」按鈕。之後就會除了會出現 HelloWorld.kon 的 widget 視窗外，也會出現一個 debug 視窗。

3. 這時候您可以在 debug 視窗中鍵入 /help 可以得到所有的除錯指令。不過您也可以直接下一個蠻有用的指令，就是 /dump helloText，便可看到 helloText 這個文字區塊的所有屬性。

4. 或者，您想試試看換一下文字區塊的內容，也可以直接在命令欄鍵入 JavaScript 的敘述 helloText.data="Hello World widget 沒有用" 之類的測試敘述，這樣 widget 的文字區塊內容會直接修改。

▲Top

如何加入互動性

剛剛提到的都是一些靜態 widget 的一些基本設定，但 widget 最重要的就是提供一些互動的功能，例如按了文字就會連結到特定網頁，或是讓使用者鍵入查詢關鍵字在進行查詢或反應，這在剛剛的教學中並沒有提到，在這一小節裡將提供這樣的資訊。

所謂的互動性就是由使用者產生的介面事件（event）觸發，例如滑鼠移動或按下（mouseMove、mouseEnter、mouseoExit、mouseUp 等）、按鍵（keyDown、keyUp 等）、甚至是系統觸發的計時器（timer），然後程式收到這樣的觸發事件針對其事件的各種屬性進行反應。

這邊我們會利用剛剛 Hello World 的範例進行改良，加入一個按鈕文字，當滑鼠指標移向該按鈕時會變色，移出時會還原，按下時會連結到 http://tw.yahoo.com/。

以下是我們會加在 HelloWorld.kon 檔中第 16（</text>）、17（</window>）行間的 XML 碼：

程式列表 4

		<text name="yahooLink">	1
			<data>連到 Yahoo!</data>
			<font>Arial</font>
			<color>#FFAAFF</color>
			<style>bold</style>
			<size>24</size>
			<hOffset>130</hOffset>
			<vOffset>150</vOffset>
			<bgOpacity>0</bgOpacity>	2
			<bgColor>#FFFFFF</bgColor>	3
			<onMouseEnter>		4
				yahooLink.bgOpacity = 255;
				yahooLink.color = "#770077";
			</onMouseEnter>
			<onMouseExit>	5
				yahooLink.bgOpacity = 0;
				yahooLink.color = "#FFAAFF";
			</onMouseExit>
			<onMouseUp>	6
				openURL("http://tw.yahoo.com/");
			</onMouseUp>
		</text>

首先我們針對這幾個幾行新增的 tag 來說明（已在上面說明者就略過）。

1 <text name="yahooLink">
從這個 tag 到 </text> 結束是我們新增的文字區塊，它具備我們要的互動性，在 JavaScript 的名稱為 yahooLink。
2 <bgOpacity>0</bgOpacity>
bgOpacity 是用來定義該文字區塊背景顏色的不透明度，其數值為 0-255，0 為完全不顯示，255 為完全顯示。目前我們暫時不讓背景顏色顯示，我們等到滑鼠指標移到這個文字區塊才會由 JavaScript 來讓其背景顏色顯示出來。
3 <bgColor>#FFFFFF</bgColor>
這是指文字區塊背景顏色的 tag，其數值跟 color tag 一樣的規則。以此為例，是個白色背景，但由於設定不透明度的 bgOpacity 為 0，因此一開始不會顯現白色背景。
4 <onMouseEnter> yahooLink.bgOpacity = 255; yahooLink.color = "#770077"; </onMouseEnter>
這段程式是一個事件處理程式（event handler），當使用者將滑鼠指標移到這個文字區塊上時，便會將文字區塊白色的背景顯現出來（yahooLink.bgOpacity = 255;），並設定文字顏色為深紫色（yahooLink.color = "#770077";）。
5 <onMouseExit> yahooLink.bgOpacity = 0; yahooLink.color = "#FFAAFF"; </onMouseExit>
跟上面的 onMouseEnter 很類似，只不過是做相反的事情。當使用者將滑鼠指標移出這個文字區塊時，便會觸發這段程式。這段程式會隱藏文字區塊背景（yahooLink.bgOpacity = 0;），然後將文字顏色還原成淺紫色（yahooLink.color = "#FFAAFF";）。
6 <onMouseUp> openURL("http://tw.yahoo.com/"); </onMouseUp>
onMouseUp tag 定義了當滑鼠按鈕按下又放開後（mouseUp）的事件處理程式。以此為例，當這個文字區塊被按後，就會開啟預系統設瀏覽器造訪 Yahoo! 奇摩網站（openURL("http://tw.yahoo.com/");）。

▲Top

加入互動性到 Hello World 範例實作 Hands-On

1. 首先回到 Notepad++，將剛剛那段程式加到 HelloWorld.kon 檔案的第 16、17 行間，然後儲存起來。

2. 回到 Yahoo! Widget Engine，直接在 Debug 視窗中按下「Reload」按鈕。然後將滑鼠指標移到「連到 Yahoo!」的文字上面，就會出現反白，按下去還會連到 Yahoo! 奇摩網站。

▲Top

構成 YWE Widget

雖然現在我們可以利用 .kon 檔案讓 YWE 環境載入，但是畢竟這只是在 widget 開發時期的暫時作法。當您的 widget 一切都就緒時，您必須將整個 widget 打包起來，方便使用者來使用您製作的 widget。要打包成 .widget 檔，可以用現成的工具 Widget Converter 或是用手動的方式。為了讓大家了解 YWE widget 的檔案結構，我們在這個範例我們使用手動方式來將這些檔案打包成 .widget 檔，我們會在 RSS Reader 新聞閱讀器 widget 中的範例用 Widget Converter 來示範打包及解開 .widget 檔案。

一般的 YWE widget 都是一個 ZIP 壓縮檔，但檔名結尾是 .widget。我們以 Hello World 這個 widget 為例，我們即將打包前我們應該先將檔案排成這樣：

以目前的 Hello World! widget 來看，除了沒有獨立的 JavaScript 檔案外，其他都有。在接下來的實作中，我們將把 Hello World Widget 打包成一個跨平台的 .widget 檔。

▲Top

打包成 .widget 範例實作 Hands-on

1. 請先製作一個名為 HelloWorld.widget 文件夾，裡面再製作一個 Contents 檔案夾。然後把剛剛製作的 HelloWorld.kon 還有 Resources 這個文件夾複製到 Contents 這個文件夾之下，就像剛剛所說的檔案結構一樣。

2. 選取剛剛製作的 HelloWorld 檔案夾，在其上按右鍵會出現下圖畫面，請選擇「傳送到」->「壓縮的 (zipped) 資料夾」，將它們壓縮成一個 zip 壓縮檔。

3. 之後會出現如下的視窗，請按「是」按鈕繼續。

4. 之後會進行壓縮，並產生一個名為 HelloWorld.zip 的 zip 壓縮檔，此時請先將原來的 HelloWorld.widget 刪除，然後將剛剛壓好的 HelloWorld.zip zip 壓縮檔檔名改為 HelloWorld.widget。之後出現確認視窗請按「是」按鈕。

5. 當重新命名完成後，會看到 HelloWorld.widget 的圖示改變成 Yahoo! Widget Engine 的 Widget 圖示。這樣就可以直接用滑鼠按兩下來執行它。

▲Top


▲前頁 ☆目次 ▼次頁