提要

提要是一種特殊視圖,用來協助引導使用者執行一系列的複雜作業,來實現某個整體目標。 比方說,提要可用來協助引導使用者完成建立、編譯和執行簡單 Java 程式時所需經歷的步驟。 提要是從說明 >提要... 功能表項目啟動的。 您也可以從簡介頁面中啟動提要。

提要利用 org.eclipse.ui.cheatsheets.cheatSheetContent 延伸點來定義。 提要內容本身則是定義在個別檔案中,因此,比較容易翻譯成其他語言。

提供提要

提要的提供方式非常簡單。 我們來看一下 JDT 所提供用來建置簡單 Java 應用程式的提要。

<extension point="org.eclipse.ui.cheatsheets.cheatSheetContent">
	<cheatsheet
		name="%cheatsheet.helloworld.name"
		contentFile="$nl$/cheatsheets/HelloWorld.xml"
		id="org.eclipse.jdt.helloworld">
		<description>%cheatsheet.helloworld.desc</description>
	</cheatsheet>
	...
非常類似其他工作台構成要素,您可以指定提要的名稱、說明和 ID。 當使用者存取說明>提要... 清單時,會顯示名稱和說明。 如果您要將多份提要放在一個邏輯群組中,您也可以定義提要的種類。 如果沒有指定任何種類,提要會出現在其他種類中。

提要對話框

提要項目

提要的真正工作是在內容檔中完成的。 內容檔是一個由 contentFile 屬性來指定名稱和位置的 XML 檔。 這個檔案的路徑是相對於外掛程式的目錄。(請注意目錄名稱中的 $nl$ 變數,它表示檔案將放在目標環境的國家語言所專用的目錄中。)

檔案格式本身包括提要的概觀資訊,後面再接著使用者將執行的各個步驟(稱為項目)的說明。 用最簡單的方式來說,項目只是使用者應該採取的步驟的詳細說明。 不過,項目也可以指定一個用來代表使用者執行步驟的動作。 我們來看看 Java 提要內容檔 (HelloWorld.xml) 的第一部分。

<?xml version="1.0" encoding="big5" ?> 
<cheatsheet title="Simple Java Application">
	<intro
		href="/org.eclipse.ui.cheatsheets.doc/tasks/tcheatst.htm">
		<description>
歡迎使用 Hello, World Java 指導教學。
它會協助您建置和試驗著名的 "hello world" 應用程式。
您將建立一個 Java 專案以及執行時在主控台印出 "hello world" 的 Java 類別。
我們就開始吧!
		</description>
</intro>
	<item
		href="/org.eclipse.platform.doc.user/concepts/concepts-4.htm"
		title="Open the Java Perspective">
		<action
			pluginId="org.eclipse.ui.cheatsheets"
			class="org.eclipse.ui.internal.cheatsheets.actions.OpenPerspective"
			param1="org.eclipse.jdt.ui.JavaPerspective"/>
		<description>
請在工作台頂端的工具列中,選取「視窗 -> 開啟視景 -> Java」。
這個步驟會變更視景來設定 Java 開發作業的 Eclipse 工作台。
您可以按「按一下執行」按鈕來自動開啟 "Java" 視景。
		</description>
</item>
...

簡單 Java 提要

提要的頂端會顯示標題和簡介資訊。 之後是項目說明。 這份提要的第一個項目說明如何開啟 Java 視景。 不但如此,action 屬性還會指定一個用來代表使用者執行動作的類別。 這個類別必須實作 IAction。 這非常方便,因為它可讓您重複使用專為了功能表或工具列構成要素而撰寫的動作類別。

如果這個動作使用參數或必須知道提要及其狀態,動作的類別可以選擇性地實作 ICheatSheetAction。 在這個情況下,會將參數陣列和指向 ICheatSheetManager 的參照傳給動作,使它能夠要求提要的其他相關資訊。 任何必要的參數都可以利用 paramN 屬性來傳給動作的 run 方法。

強烈建議您,如果執行動作有可能失敗,便讓提要所呼叫的動作報告順利完成或失敗的結果。 (比方說,使用者可能會從對話框取消動作。) 請參閱 IAction.notifyResult(boolean),以取得詳細資料。

項目不需要定義動作。 如果使用者必須手動執行您的項目,您就完全不需要指定動作。 以下是 Java 提要的第三步驟,它只是告訴使用者如何編寫簡單應用程式。 當沒有指定任何動作時,項目說明必須指示使用者在作業完成之後按下適當按鈕。

<item
	href="/org.eclipse.jdt.doc.user/tasks/tasks-54.htm"
	title="Add a System.out.println line in your main method">
	<description>
現在,您已有 HelloWorld 類別,請在 "public static void main" 方法中加入下列陳述式:
System.out.println("Hello world!");,再儲存變更。完成之後,請按下面的「完成時按一下」
按鈕。
	</description>
</item>
其他屬性用來控制能不能完全跳過的項目,以及如果使用者在執行步驟時要求說明,應該啟動哪一份文件。 請參閱 org.eclipse.ui.cheatsheets.cheatSheetContent 延伸點文件,以取得提要內所能定義的所有屬性的說明。
子項目

您可以定義子項目來進一步組織項目的呈現方式。 子項目不像項目,沒有特定的造訪次序。 子項目也可以定義動作來自動執行使用者的子作業。 子項目動作的說明方式和項目動作相同。

條件表示式和提要變數

您可以利用條件表示式來定義內容或行為會因是否符合特定條件而不同的提要元素。 條件是在子項目的 condition 元素中,利用針對每個選項的 when 屬性來進行比對的任意字串值來說明的。 條件通常會利用 ${var} 形式來參照提要變數,其中 var 指向某個提要變數的名稱。 少數簡單範例有助於示範條件表示式的運作方式。

您可以利用條件式子項目,從可能的子項目清單中選取一個子項目。 只有第一個 when 屬性符合 condition 屬性的子項目會併入提要中。 例如:

<item ...>
	<conditional-subitem condition="${v1}">
		<subitem when="a" label="Step for A." />
		<subitem when="b" label="Step for B." />
	</conditional-subitem>
</item>
這個項目指定兩個可能的子項目,它們會隨著 v1 變數值而不同。 如果變數值是 a,就會併入第一個子項目。 如果變數值是 b,就會併入第二個子項目。 如果變數不是這兩個值,就會將它視為錯誤。

條件性動作類似於條件式子項目。 perform-when 元素用來指定在一份可能動作的清單中執行某個動作的條件。 條件的說明方式相同,使用通常會參照某個變數的任意字串。 when 屬性符合條件的動作就是將執行的動作。 例如:

<item ...>
	<perform-when condition="${v1}">
		<action when="a" class="com.example.actionA" pluginId-"com.example" />
		<action when="b" class="com.example.actionB" pluginId-"com.example" />
	</perform-when>
</item>
要執行的動作是根據 v1 變數值來選取的。 如果變數值既不是 a,也不是 b ,就會將它視為錯誤。
重複的子項目

重複的子項目說明可展開成 0、1 或更多個類似子步驟的子項目。 子步驟是利用特殊變數 ${this} 來個別化。 values 屬性所指定的值會取代這個變數。 values 屬性是用逗點分隔的值字串。 在 values 屬性中,可以使用展開成一份值清單的變數。 例如:

<item ...>
	<repeated-subitem values="${v1}">
		<subitem label="Step ${this}" />
	</repeated-subitem>
</item>
如果變數值是 1,b,three,則三個子項目都會出現在提要中,每個都有唯一標籤("Step 1"、"Step b"、"Step three")。 變數可用在標籤或動作參數值中。 當動作在執行中,也可以從 ICheatSheetManager 中存取它。

提要接聽器

在某些情況下,如果提要在作用中,您可能想變更 UI 的其餘部分。 比方說,如果提要在引導使用者執行編輯作業,您可能會有一個顯示特殊註釋的編輯器。 在這個情況下,您可以將接聽器指定成提要的屬性。 接聽器屬性必須是繼承 CheatSheetListener 的 Java 類別完整名稱。 當提要的生命周期有了改變時,比方說,提要開啟、關閉或完成,接聽器會收到通知和 ICheatSheetEvent

將屬性提供給現有的提要

org.eclipse.ui.cheatsheets.cheatSheetItemExtension 延伸規格可用來將任意屬性提供給預先存在的提要。 這個延伸點的用途是讓外掛程式新增其他按鈕來協助使用者執行給定的步驟。 這些其他按鈕顯示在說明圖示旁。

如果要使用這個機制,您可以在提要 XML 檔中的項目定義內定義任何任意屬性。 屬性名稱會針對 org.eclipse.ui.cheatsheets.cheatSheetItemExtension 延伸規格中所提供的任何屬性來進行比對。 請參閱延伸點文件,以取得詳細資料。