3.0 版
這份文件用一系列的 DTD 片段(機器可讀的 XML 綱目)來說明提要內容檔的結構。
cheatsheet
<!ELEMENT cheatsheet (intro, item+)> <!ATTLIST cheatsheet title CDATA #REQUIRED >
<cheatsheet> 元素定義提要內容檔的主體。 <cheatsheet> 的屬性如下:
intro
<!ELEMENT intro (description)> <!ATTLIST intro contextId CDATA #IMPLIED href CDATA #IMPLIED >
<intro> 元素用來說明要顯示的提要簡介。 <description> 子元素包含簡介的主體。 <intro> 的屬性如下:
description
<!ELEMENT description EMPTY> <!ATTLIST description >
<description> 元素用來保留提要或提要項目的說明。 說明由簡單的格式化標示所解譯的文字組成。 提要會自動格式化和佈置文字,使它合理呈現在 UI 中。 在文字之內,對稱的 <b>...</b> 標示會使含括的文字呈現粗體,<br/> 元素可用來強迫換行。 目前只支援這些格式化標示(不過,將來可能會加入其他格式化標示)。 文字中的某些字元在 XML 剖析器中有特別意義;特別是要分別寫入 "<"、">"、"&"、"'" 和 """(雙引號),而不是寫入 "<"、">"、"&" 、"'" 和 """。 空白字元(空格和換行)是當作單字分隔字元來處理的;相鄰的空格和換行會當作單一單元來處理,且會呈現為單一空格和換行。 系統不處理緊接在 <description> 和 <br/> 標示之後的空白字元,在 </description> 標示之前的空白字元會保留原狀。
item
<!ELEMENT item (description ([action|perform-when] | (subitem|repeated-subitem|conditional-subitem)*))> <!ATTLIST item title CDATA #REQUIRED skip ("true" | "false") "false" contextId CDATA #IMPLIED href CDATA #IMPLIED >
每個 <item> 元素都會說明提要中的一個最上層步驟。 <item> 可能是簡單或複合的。 <item> 的屬性如下:
org.eclipse.ui.cheatsheets.cheatSheetItemExtension 可讓項目的其他自訂控制項顯示在 UI 中。 這個延伸點的構成要素會宣告可能出現在 <item> 元素的其他字串值屬性的名稱。
簡單項目有一個說明和一個選用的動作。 在一般呈現中,使用者多半能夠見到提要項目的標題。 只有當步驟是在執行程序中,才會顯示項目的說明。 <action>(或 <perform-when>)元素的存在通常會與使用者能夠按一下來執行步驟動作的按鈕相關聯。 如果動作不存在,這個步驟就是使用者必須手動執行,再明確表示他們已順利完成的步驟。
複合步驟會依照 <subitem> 子元素所指定而分解成子步驟。 使用者必須遵循嚴格的項目順序,但給定項目的子項目可以依照任何次序來執行。 項目內的所有子項目都必須嘗試(或跳過),之後,才能進入下一個項目。 (這表示必須依順序執行的動作不能用子項目來表示。)
<conditional-subitem> 子元素可讓步驟依先前的步驟已取得值的提要變數來調整子步驟的呈現。 <repeated-subitem> 子元素可讓步驟併入一組類似的子步驟。 同樣地,確切的一組子步驟也可以是基於已在先前的步驟中取得值的提要變數。
subitem
<!ELEMENT subitem ( [action|perform-when] )> <!ATTLIST subitem label CDATA #REQUIRED skip ("true" | "false") "false" when CDATA #IMPLIED >
每個 <subitem> 元素都會說明提要中的一個子步驟。 <subitem> 會帶著一個簡單的文字標籤,但沒有較長的說明也沒有進一步的子項目。 <subitem> 的屬性如下:
子項目有一個選用的動作。 <action>(或 <perform-when>)元素的存在通常會關聯於使用者能夠按一下來執子步驟動作的按鈕。 如果動作不存在,這個子步驟就是使用者必須手動執行,再明確表示他們已順利完成的步驟。
項目必須遵循嚴格的順序,但給定項目的子項目可以依照任何次序來執行。 項目內的所有子項目都必須嘗試(或跳過),之後,才能進入下一個項目。 (這表示必須依順序執行的動作不能用子項目來表示。)
conditional-subitem
<!ELEMENT conditional-subitem (subitem+)> <!ATTLIST conditional-subitem condition CDATA #REQUIRED >
各個 <conditional-subitem> 元素用來說明形式可能會隨著項目展開時之已知條件而不同的單一子步驟。 <conditional-subitem> 的屬性如下:
<conditional-subitem> 元素的 condition 屬性用來提供字串值(這個值一定來自提要變數)。 每個 <subitem> 子項必須帶著含有明確字串值的 when 屬性。 當項目展開時,含相符的值的 <subitem> 元素會取代 <conditional-subitem> 元素。 如果沒有含相符的值的 <subitem> 元素,就會將它視為錯誤。
比方說,如果名稱為 "v1" 的提要變數有 "b" 值,當展開下列項目時
<item ...> <conditional-subitem condition="${v1}"> <subitem when="a" label="Step for A." /> <subitem when="b" label="Step for B." /> </conditional-subitem> </item>就會選取第二個子項目,且項目會展開成相當於下列內容
<item ...> <subitem label="Step for B."/> </item>
repeated-subitem
<!ELEMENT repeated-subitem (subitem)> <!ATTLIST repeated-subitem values CDATA #REQUIRED >
各個 <repeated-subitem> 元素用來說明展開成 0、1 或更多個類似子步驟的子項目。 <repeated-subitem> 的屬性如下:
values 屬性提供逗號分隔的字串清單;<subitem> 子項提供範本。 當項目展開時,含有對應的字串值所取代的 "this" 變數之 <subitem> 元素的副本會取代 <repeated-subitem> 元素。
比方說,如果名稱為 "v1" 的提要變數有 "1,b,three" 值,當展開下列項目時
<item ...> <repeated-subitem values="${v1}"> <subitem label="Step ${this}."> <action class="com.xyz.myaction" pluginId="com.xyz" param1="${this}"/> </subitem> </repeated-subitem> </item>項目會展開成相當於下列內容:
<item ...> <subitem label="Step 1."> <action class="com.xyz.myaction" pluginId="com.xyz" param1="1"/> </subitem> <subitem label="Step b."> <action class="com.xyz.myaction" pluginId="com.xyz" param1="b"/> </subitem> <subitem label="Step three."> <action class="com.xyz.myaction" pluginId="com.xyz" param1="three"/> </subitem> </item>
action
<!ELEMENT action EMPTY> <!ATTLIST action class CDATA #REQUIRED pluginId CDATA #REQUIRED param1 CDATA #IMPLIED ... param9 CDATA #IMPLIED confirm ("true" | "false") "false" when CDATA #IMPLIED >
每個 <action> 元素都會說明提要中的一個動作。 <action> 的屬性如下:
org.eclipse.jface.action.IAction
之 Java 類別的完整名稱。
如果這個動作也實作 org.eclipse.ui.cheatsheets.ICheatSheetAction
,就會用它的 run(String[],ICheatSheetManager) 方法來呼叫它,且會將提要管理程式和動作參數傳給它。
每當這個屬性存在時,pluginId 屬性也必須存在。
強烈建議您,如果執行動作有可能失敗(也許是因為使用者從對話框取消動作),提要所要呼叫的動作應該要報告順利完成或失敗的結果。
(請參閱 org.eclipse.jface.action.Action.notifyResult(boolean),以取得詳細資料。)
org.eclipse.ui.cheatsheets.ICheatSheetAction
的動作類別時,會將這些屬性的字串值傳給動作。
您可以傳遞最多 9 個參數給提要動作(param1、param2 等)
. 提供的參數必須從參數 1 開始,再繼續下去;也就是說,如果 param1 不存在,指定 param2 是不合法的。
如果屬性字串的形式是 "${var}",它就被視為指向提要變數 var 的參照,且條件值就是在所在的 <item> 元素開始執行時的提要變數值(如果這時未連結變數,就是空字串)。
perform-when
<!ELEMENT perform-when (action+)> <!ATTLIST perform-when condition CDATA #REQUIRED >
每個 <perform-when> 元素都會說明提要中的一個動作。 <perform-when> 的屬性如下:
<conditional-subitem> 元素的 condition 屬性用來提供字串值(這個值一定來自提要變數)。 每個 <subitem> 子項必須帶著含有明確字串值的 when 屬性。 當項目展開時,含相符的值的 <subitem> 元素會取代 <conditional-subitem> 元素。 如果沒有含相符的值的 <subitem> 元素,就會將它視為錯誤。
比方說,如果名稱為 "v1" 的提要變數有 "b" 值,當展開下列項目時
<item ...> <subitem label="Main step"> <perform-when condition="${v1}"> <action when="a" class="com.xyz.action1" pluginId="com.xyz" /> <action when="b" class="com.xyz.action2" pluginId="com.xyz" /> </conditional-subitem> </subitem> </item>就會選取第二個動作,且項目會展開成相當於下列內容
<item ...> <subitem label="Main step"> <action class="com.xyz.action2" pluginId="com.xyz" /> </subitem> </item>
以下是非常簡單的提要內容檔的範例:
<?xml version="1.0" encoding="UTF-8"?> <cheatsheet title="Example"> <intro> <description>Example cheat sheet with two steps.</description> </intro> <item title="Step 1"> <description>This is a step with an action.</description> <action class="com.xyz.myaction" pluginId="com.xyz"/> </item> <item title="Step 2"> <description>This is a fully manual step.</description> </item> </cheatsheet>
Copyright (c) 2004 IBM Corporation and others.
All rights reserved. 這個程式和檢附的資料是遵循這項分送檢附的 Eclipse Public License 1.0 版的條款而提供的,
請造訪下列網址來取得此條款:http://www.eclipse.org/legal/epl-v10.html