虎の巻

虎の巻は、複雑な一連のタスクでユーザーをガイドして全般的なゴールを達成するための特別なビューです。 例えば、虎の巻は、単純な 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 を指定できます。 名前および説明は、ユーザーが「ヘルプ」>「虎の巻...」のリストにアクセスすると表示されます。 虎の巻を複数の論理グループに分ける場合には、虎の巻のカテゴリーを定義することもできます。 カテゴリーを指定しない場合には、虎の巻は「その他」カテゴリーに表示されます。

虎の巻ダイアログ

虎の巻の項目

虎の巻の実際の作業は、コンテンツ・ファイルで行います。 コンテンツ・ファイルは XML ファイルで、ファイルの名前および場所は contentFile 属性で指定されています。 ファイルのパスは、プラグイン・ディレクトリーへの相対パスです。 (ディレクトリー名で使用されている $nl$ 変数は、このファイルが、 ターゲット環境の各国語に対応するディレクトリーに配置されていることを意味していることに注意してください。)

ファイル・フォーマット自体には、虎の巻の概要情報、その後にユーザーが実行する各ステップ (項目 と呼ぶ) の記述が含まれています。 簡単に言えば、項目は、ユーザーが行う必要があるステップの詳細な記述です。 ただし、項目は、ユーザーに代わってステップを実行可能なアクションの実行も指定できます。 ここで、Java の虎の巻のコンテンツ・ファイル (HelloWorld.xml) の最初の部分を示します。

<?xml version="1.0" encoding="UTF-8" ?>
<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="Java パースペクティブを開く">
		<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 属性を使用してそのアクションの実行メソッドに渡すことができます。

アクションの実行が失敗する可能性がある場合 (例えば、ユーザーがダイアログからアクションをキャンセルする場合)、 虎の巻から呼び出されるアクションで成功か失敗かの結果をレポートさせることを強くお勧めします。 詳しくは、 IAction.notifyResult(boolean) を参照してください。

項目は、アクションを定義する必要はありません。 ユーザーが項目を手動で実行する必要がある場合には、アクションを指定する必要はまったくありません。 次のステップは、Java 虎の巻の 3 番目のステップです。このステップでは、単純なアプリケーションのコーディング方法のみが説明されます。 アクションが指定されていない場合には、項目の記述によって、タスクの完了後に適切なボタンを押すようにユーザーに指示する必要があります。

<item
	href="/org.eclipse.jdt.doc.user/tasks/tasks-54.htm"
	title="main メソッドの System.out.println 行の追加">
	<description>
これで HelloWorld クラスが用意できました。
「public static void main」メソッドで、ステートメント System.out.println("Hello world!"); を追加し、変更を保存します。
完了したら、下にある「終わったらクリック」ボタンを押します。
	</description>
</item>
追加属性は、項目を完全にスキップできるかどうか、ステップの実行中にユーザーがヘルプを要求した場合にどの文書を起動すべきかを制御します。 虎の巻に定義可能なすべての属性の記述については、 org.eclipse.ui.cheatsheets.cheatSheetContent 拡張ポイントの資料を参照してください。
サブ項目

項目の表示をさらに細かく編成するために、サブ項目を定義することができます。 サブ項目は、項目とは異なり、特定の順序で実行する必要はありません。 サブ項目は、ユーザーに代わってサブタスクを自動的に実行するアクションを定義する場合もあります。 サブ項目アクションは、項目のアクションと同じ方法で記述されます。

条件式および虎の巻の変数

条件式は、そのコンテンツまたは振る舞いが、特定の条件が true になることが条件となる虎の巻エレメントを定義するために使用することができます。 条件は、それぞれの選択の when 属性と突き合わせられる任意のストリング値を使用して、 サブ項目の condition エレメント内に記述します。 条件は、通常は ${var} という形式を使用して虎の巻の変数を参照します。ここで var は虎の巻の変数の名前です。 いくつかの簡単な実例が、条件式の働きを理解する助けになります。

条件付きサブ項目は、選択可能なサブ項目リストから、サブ項目を 1 つ選択するために使用できます。 when 属性が条件属性と一致した最初のサブ項目のみが、虎の巻に組み込まれます。 例:

<item ...>
	<conditional-subitem condition="${v1}">
		<subitem when="a" label="A のステップ。" />
		<subitem when="b" label="B のステップ。" />
	</conditional-subitem>
</item>
この項目は、変数 v1 の値に依存する 2 つの使用可能なサブ項目を指定します。 変数値が a の場合には、最初のサブ項目が組み込まれます。 変数値が b の場合には、2 番目のサブ項目が組み込まれます。 変数がいずれの値でもない場合には、エラーと見なされます。

条件付きアクションも、条件付きサブ項目と同様です。 perform-when エレメントは、実行可能なアクション・リストの中のアクションを 1 つ実行するための条件を指定します。 条件は、変数を頻繁に参照する任意のストリングを使用して、同様の方法で記述されます。 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 の場合には、3 つのサブ項目が虎の巻に表示され、それぞれに固有のラベル (「Step 1,」「Step b,」「Step three」) が付いています。 変数は、ラベルまたはアクション・パラメーター値で使用できます。 変数は、アクションの実行中に ICheatSheetManager からもアクセスできます。

虎の巻のリスナー

虎の巻がアクティブの場合に、ユーザー UI の他のパーツを変更する必要がある場合があります。 例えば、虎の巻でユーザーの編集タスクをガイドしているときに、特別な注釈を表示するエディターを使用する場合があります。 この場合には、listener を虎の巻の属性として指定できます。 listener 属性は、CheatSheetListener をサブクラス化する Java クラスの完全修飾名でなければなりません。 リスナーは、オープン、クローズ、または完了など、虎の巻のライフ・サイクルに変更があると、ICheatSheetEvent と共に通知を受信します。

既存の虎の巻への属性の組み込み

org.eclipse.ui.cheatsheets.cheatSheetItemExtension 拡張は、既存の虎の巻に任意の属性をコントリビュートするために使用できます。 この拡張ポイントの目的は、プラグインが、所定のステップでユーザーを支援する追加ボタンを追加できるようにすることです。 これらの追加ボタンは、ヘルプ・アイコンの横に表示されます。

このメカニズムを使用するために、虎の巻 XML ファイル内の項目定義内に、 任意の属性を定義できます。 属性の名前は、 org.eclipse.ui.cheatsheets.cheatSheetItemExtension 拡張にコントリビュートされている任意の属性と突き合わせられます。 詳しくは、拡張ポイントの資料を参照してください。