バージョン 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 パーサーにとって特殊な意味を持ちます。 特に、「<」、「>」、「&」、「'」、および「"」(引用符) を書くには、 それぞれ代わりに「<」、「>」、「&」、「'」、および「"」を使用します。 空白文字 (スペースおよび改行) は語のセパレーターとして扱われます。 また、隣接するスペースおよび改行は、単一ユニットとして扱われ、1 つのスペースまたは 1 つの改行として表現されます。 <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> エレメントは、虎の巻内の 1 つのトップレベル・ステップを記述します。 <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 属性を持っている必要があります。 項目が展開されると、<conditional-subitem> エレメントは、 一致する値を持つ <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>このとき、2 番目のサブ項目が選択され、項目は以下と同等のものに展開されます。
<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> の子はテンプレートを提供します。 項目が展開されると、<repeated-subitem> エレメントは、対応するストリング値によって 置換される変数 "this" を持つ <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) メソッドを介して呼び出され、
虎の巻マネージャーとアクション・パラメーターが渡されます。
この属性が表示されるときは必ず、プラグイン ID 属性も表示されていなければなりません。
アクションの実行が失敗する可能性がある場合 (ユーザーがダイアログからアクションをキャンセルした場合など)、
虎の巻から呼び出される予定のアクションに
成功か失敗の結果をレポートさせるようにすることを強くお勧めします
(詳細については 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 属性を持っている必要があります。 項目が展開されると、<conditional-subitem> エレメントは、 一致する値を持つ <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>このとき、2 番目のアクションが選択され、項目は以下と同等のものに展開されます。
<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.
This program and the accompanying materials are made
available under the terms of the Eclipse Public License v1.0 which accompanies
this distribution, and is available at
http://www.eclipse.org/legal/epl-v10.html