メニューおよびツールバー・パス

アクションのロケーション用のパスを指定する多くのアクション組み込みについて説明しました。これらのパスがどのような意味を持つのかについて詳しく説明します。   

メニュー・パス

ワークベンチの「ヘルプ」メニューを見てメニュー・パスについて考えてみましょう。

ワークベンチ内の名前付きグループ

新規メニューおよびメニュー項目を挿入するロケーションは、名前付きグループを使用して定義されます。 名前付きグループは、メニュー・バーまたはプルダウン・メニュー内のあるポイントに、 メニュー項目を挿入できるようにするスロットまたはプレースホルダーとして考えることができます。

ワークベンチは、IWorkbenchActionConstants および IIDEActionConstants クラス内のすべてのグループ・スロット名を定義します。 (リソース関連のメニュー項目は汎用ワークベンチ外の要因となるため、2 種類のクラスが使用されています)。 名前付きグループは、ワークベンチ・メニューごとに、 プラグインが新規アクションを挿入すると予期されているロケーションのメニューに配置されます。

以下のヘルプ・メニューの説明は、 IWorkbenchActionConstants クラス定義を基に作り替えたものです。

   Standard Help menu actions
   Start group - HELP_START - "start"
   End group - HELP_END - "end"

標準ワークベンチ・ヘルプ・メニューは、"start" と呼ばれる名前付きグループを定義します。 このグループには、"end" と呼ばれる名前付きグループが続きます。 2 つのグループを定義すると、コントリビュートされる項目が配置されるヘルプ・メニュー内の位置をプラグインがさらに制御できるようになります。 メニューを定義する際は、任意の数のスロットを定義することができます。 さらにスロットを追加することにより、 他のプラグインに、それらの組み込みが既存の組み込みに関連して表示される場所について、より多くのコントロールを与えます。

ヘルプ・メニューにメニュー項目を追加するプラグインでは、これらのグループ名を使用して、メニュー項目を配置する位置を決められます。 例えば、cheatsheet プラグインは、「虎の巻...」メニューを含むアクション・セットをワークベンチに追加します。 以下に、org.eclipse.ui.cheatsheets プラグインの plugin.xml のマークアップを示します。

<extension
	point="org.eclipse.ui.actionSets">
	<actionSet
		label="%CHEAT_SHEETS"
		visible="true"
		id="org.eclipse.ui.cheatsheets.actionSet">
		<action
			label="%CHEAT_SHEETS_MENU"
			class="org.eclipse.ui.internal.cheatsheets.actions.CheatSheetHelpMenuAction"
			menubarPath="help/helpStart"
			id="org.eclipse.ui.cheatsheets.actions.CheatSheetHelpMenuAction">
		</action>
	</actionSet>
</extension>

新規のヘルプ・アクションは、helpStart グループ内のヘルプ・メニューに配置されます。

完全修飾メニュー・パス

完全なメニュー・パスは、単に「メニュー名/グループ名」です。ワークベンチのほとんどのメニュー名は、 IWorkbenchActionConstants に定義されています。 (リソース関連のメニュー名は、IIDEActionConstants に定義されます。) このクラスのヘルプ・メニューの名前を見れば、ヘルプ・アクションの完全修飾パス名が「help/helpEnd」であることが分かります。

メニューの中には、ネストされたサブメニューを持つものもあります。 これが、長いパスが効果を表すところです。ヘルプ・メニューが、 「submenuStart」という名前付きグループを持つ「submenu」というサブメニューを定義した場合、 新規サブメニュー内のアクションの完全修飾メニュー・パスは、「help/submenu/submenuStart」になります。

UI ラベルの外部化

上記の例は、UI に表示されるストリングを外部化するための技法について示しています。外部化されたストリングは、 プラグインの UI を他の言語へ簡単に翻訳するために使用されます。 ストリングをキー (%CHEAT_SHEETS_MENU) で置換し、plugin.properties ファイル内に次の形式のエントリーを作成することにより、 plugin.xml ファイル内のストリングを外部化することができます。

	CHEAT_SHEETS_MENU = 虎の巻...

plugin.properties ファイルは、異なる言語用に変換することができ、plugin.xml を変更する必要はありません。

新規メニューおよびグループの追加

これまでに説明した多くの例で、サンプル・プラグインによって組み込まれたアクションは、 メニュー内の既存の名前付きグループへ追加されました。

actionSetsviewActionseditorActions、および popupMenus の各拡張ポイントを 使用しても、組み込み内で新規メニューおよびグループを定義することができます。 つまり、新規サブメニューまたは新規プルダウン・メニューを定義し、 アクションをこれらの新規メニューへ組み込むことができます。 この場合、新規アクションのパスには、新規に定義したメニューの名前が含まれます。

この技法は、README ツールがアクション・セット用に新規メニューを定義したときに説明しました。  より詳細にメニュー・パスを見てきたところで、そのマークアップをもう一度見てみましょう。

   <extension point = "org.eclipse.ui.actionSets">
   <actionSet id="org_eclipse_ui_examples_readmetool_actionSet"
	   label="%ActionSet.name"
	   visible="true">
	   <menu id="org_eclipse_ui_examples_readmetool"
		   label="%ActionSet.menu"
		   path="window/additions">
		   <separator name="slot1"/>
		   <separator name="slot2"/>
		   <separator name="slot3"/>
	   </menu>
	   <action id="org_eclipse_ui_examples_readmetool_readmeAction"
		   menubarPath="window/org_eclipse_ui_examples_readmetool/slot1"
		   toolbarPath="readme"
		   label="%ReadmeAction.label"
		   tooltip="%ReadmeAction.tooltip"
		   helpContextId="org.eclipse.ui.examples.readmetool.open_browser_action_context"
		   icon="icons/ctool16/openbrwsr.png"
		   class="org.eclipse.ui.examples.readmetool.WindowActionDelegate"
		   enablesFor="1">
		   <selection class="org.eclipse.core.resources.IFile"
				name="*.readme">
		   </selection>
	   </action>
	   ...

"org_eclipse_ui_examples_readmetool" と呼ばれる新しいメニュー名を追加します。  そのラベルは、プロパティー・ファイルのキー "%ActionSet.name" によって定義されています。 このメニューでは、"slot1"、"slot2"、および "slot3" の 3 つの名前付きグループを定義します。  この新規メニューをパス "window/additions" に追加します。  

IWorkbenchActionConstants へ戻ると、javadoc 内のウィンドウ・メニューのこの定義が見られます。

    * <h3>Standard Window menu actions</h3>
    * <ul>
    * <li>Extra Window-like action group (<code>WINDOW_EXT</code>)</li>

クラス定義をさらに見ていくと、以下の関連定義が見えるでしょう。

   public static final String MENU_PREFIX = "";
   ...
   public static final String M_WINDOW = MENU_PREFIX+"window";
   ...
   public static final String MB_ADDITIONS = "additions";  // Group.
   ...
   public static final String WINDOW_EXT = MB_ADDITIONS;   // Group.

この情報から、ワークベンチ "Window" メニューへ何かを追加するために、パスをつなぎ合わせることができます。  メニュー自体は、"window" と呼ばれ、"additions "というスロットを 1 つ定義します。  新規メニューを追加するには、パス "window/additions" を使用します。

アクション・セット宣言で、 パス "window/org_eclipse_ui_examples_readmetool/slot1" を使用して、 アクションを新規に定義されたメニューへ追加します。

他のプラグインは、独自のメニューの 1 つを追加するために、 この同じパス (または他のスロットのうちの 1 つ) を使用することにより、メニューに追加することができます。  

README ツールの例では、separator 属性を使用してグループ名を識別します。 これで、グループに項目が含まれているときにグループ間に分離線が表示されます。 グループを区別するためのセパレーターをメニューに表示せずに名前付きグループを定義したい場合は、 代わりに groupMarker 属性を使用することができます。

ツールバー・パス

ツールバー・パスは、メニュー・パスと同様に機能します。  

ワークベンチ内の名前付きツールバー

ワークベンチ・ツールバーは、 ワークベンチ自体を含むさまざまなプラグインによって提供されるツールバーで構成されます。 特定のツールバー内には、 新規ツールバー項目を挿入するために使用できる名前付きグループまたはスロットがあります。    

次のワークベンチ・ツールバーの記述は、 IWorkbenchActionConstants クラス定義を元に作り替えたものです。

// Workbench toolbar ids
public static final String TOOLBAR_FILE = "org.eclipse.ui.workbench.file"
public static final String TOOLBAR_NAVIGATE = "org.eclipse.ui.workbench.navigate";

// Workbench toolbar group ids.  To add an item at the beginning of the group,
// use the GROUP id.  To add an item at the end of the group, use the EXT id.
public static final String PIN_GROUP = "pin.group";
public static final String HISTORY_GROUP = "history.group";
public static final String NEW_GROUP = "new.group";
public static final String SAVE_GROUP = "save.group";
public static final String BUILD_GROUP = "build.group"; 

最も単純な場合では、プラグインによって、独自のツールバーにツールバー項目を提供できます。 例えば、メニューに提供された README ツール・アクションは、ツールバー・パスにも提供されます。

<action id="org_eclipse_ui_examples_readmetool_readmeAction"  
   menubarPath="window/org_eclipse_ui_examples_readmetool/slot1"
   toolbarPath="readme"
...

ワークベンチ・ツールバー・パスまたはグループへの参照がないため、README アクションは、 ツールバー上の独自のグループに表示されます。 その代わり、次のパスを指定すると、file ツールバー内の項目が save グループに置かれます。

...
<action id="org_eclipse_ui_examples_readmetool_readmeAction"  
   menubarPath="window/org_eclipse_ui_examples_readmetool/slot1"
   toolbarPath="org.eclipse.ui.workbench.file/save.group"
...

IWorkbenchActionConstants に定義されているパスは、他のプラグインのツールバー・パスで参照される可能性があります。

別のプラグインのアクション・セットの追加

プラグインのツールバー項目を、 別のプラグインのアクションとさらに統合したい場合について考えてみましょう。 外部ツール・プラグイン (org.eclipse.ui.externaltools) で、そのアクションをデバッガー・ツールバーと統合する方法について見てみましょう。 デバッガー (org.eclipse.debug.ui) は、次のようにツールバー・アクションを定義します。

<extension
      point="org.eclipse.ui.actionSets">
   <actionSet
         label="%LaunchActionSet.label"
         visible="false"
         id="org.eclipse.debug.ui.launchActionSet">
   ...
   <action
         toolbarPath="debug"
         id="org.eclipse.debug.internal.ui.actions.RunDropDownAction"
         hoverIcon="icons/full/ctool16/run_exc.png"
         class="org.eclipse.debug.internal.ui.actions.RunToolbarAction"
         disabledIcon="icons/full/dtool16/run_exc.png"
         icon="icons/full/etool16/run_exc.png"
         helpContextId="run_action_context"
         label="%RunDropDownAction.label"
         pulldown="true">
   </action>
   ...

README ツールと同様に、デバッガー・プラグインは独自のツールバー・パスを定義します。 これは、そのツールバー項目が、ワークベンチ上の独自のツールバー内にあるということです。 外部ツール・プラグインは何を行うでしょうか?

<extension point="org.eclipse.ui.actionSets">
	<actionSet
		id="org.eclipse.ui.externaltools.ExternalToolsSet"
		label="%ActionSet.externalTools"
		visible="true">
		...
		<action
			id="org.eclipse.ui.externaltools.ExternalToolMenuDelegateToolbar"
			definitionId= "org.eclipse.ui.externaltools.ExternalToolMenuDelegateToolbar"
			label="%Action.externalTools"
			toolbarPath="org.eclipse.debug.ui.launchActionSet/debug"
			disabledIcon="icons/full/dtool16/external_tools.png"
			icon="icons/full/etool16/external_tools.png"
			hoverIcon="icons/full/ctool16/external_tools.png"
			tooltip="%Action.externalToolsTip"
			pulldown="true"
			class="org.eclipse.ui.externaltools.internal.menu.ExternalToolMenuDelegate">
		</action>
	</actionSet>
</extension>

ツールバー・パス内のデバッガーのアクション・セット ID の使用に注意してください。 パスにアクション・セット ID を使用するということは、ツールバー項目が、 参照されるアクション・セットに使用されるツールバーに置かれるということを意味します。 ツールバー・グループ内では、項目はアクション・セット ID 順に表示されます。 このため、この例では、外部ツール・アクションはデバッガー・アクションの後に表示されます。  

アクション・セットのツールバーへの追加を行うとき、新規グループも定義できます。 外部ツール・プラグインが "org.eclipse.debug.ui.launchActionSet/external" としてその toolbarpath を定義した場合、アクションの新規グループもツールバー上に作成されます。 メニューと同様に、ツールバー・グループにはセパレーターが引かれます。  

別のプラグインからのパスの使用

一般に、plugin.xml からパス名を取得することによって別のプラグインのメニューまたはツールバーを組み込むことは、 そのパス名がクライアントで使用可能であると明確にマークされていない限り、 良い方法ではありません。 プラグインの今後のバージョンでパス名が変更される可能性があります。 プラグインのアクション・セット ID およびパスを適切なものとしてマークするには、2 つの一般的な方法があります。