説明: この拡張ポイントは、別のプラグインが所有するコンテキスト・メニューに 新しいアクションを追加するために使用されます。 アクション contribution は、特定のオブジェクト・タイプ (objectContribution) に対して、あるいは ビューまたはエディター・パーツの特定のコンテキスト・メニュー (viewerContribution) に対して実行される場合があります。 objectContribution の使用時に、指定のタイプのオブジェクトが選択された ビューまたはエディター・パーツのすべてのコンテキスト・メニューに contribution が表示されます。 一方、viewerContribution の使用時には、選択に関係なく、ビューまたはエディター・パーツの 指定のコンテキスト・メニューにのみ contribution が表示されます。
選択が異種混合である場合、contribution は、共通タイプの選択に登録された場合に適用されます。 直接のマッチングが不可能な場合、スーパークラスおよびスーパーインターフェースとのマッチングが 試みられます。
選択は、名前フィルターにより、さらに制約することができます。 フィルターを使用した場合、contribution を適用するには、選択内のすべてのオブジェクトがフィルターに マッチする必要があります。
オブジェクト contribution の個々のアクションは、属性 enablesFor を 使用して、single、multiple、any other のいずれの選択タイプにのみ適用するのかを指定できます。
これらのフィルター・メカニズムでは不十分な場合、アクション contribution は filter メカニズムを使用することがあります。 この場合、ターゲット・オブジェクトの属性は、一連の名前値のペアで記述されます。 選択に対して適用される属性は、選択タイプに固有で、ワークベンチのドメインの範囲外であるため、ワークベンチは、 実際の選択に対し、このレベルにおけるフィルター操作を代行しています。
アクションの使用可能性と可視性は、エレメント enablement と visibility をそれぞれ使用することによって定義できます。 これらの 2 つのエレメントにはブール式が含まれ、この式が評価されて使用可能性と可視性を決定します。
enablement エレメントと visibility エレメントは同じ構文です。 どちらにも、1 つのブール式サブエレメントだけが含まれています。 最も単純なケースでは、これは 1 つの objectClass、objectState、pluginState、または systemProperty エレメントになります。 もっと複雑なケースになると、and、or、および not のエレメントで結合して、1 つのブール式を構成している場合があります。 and および or エレメントの両方に、2 つのサブエレメントが含まれていなければなりません。 not エレメントには、 1 つのサブエレメントだけが含まれなければなりません。
構成マークアップ:
<!ELEMENT extension (objectContribution , viewerContribution)>
<!ATTLIST extension
point CDATA #REQUIRED
id CDATA #IMPLIED
name CDATA #IMPLIED
>
<!ELEMENT objectContribution (filter* , visibility? , menu* , action*)>
このエレメントは、指定されたタイプのオブジェクトが選択される ビューアー・コンテキスト・メニューに対してアクションおよび/またはメニューのグループを定義するために使用されます。
<!ATTLIST objectContribution<!ELEMENT viewerContribution (visibility? , menu* , action*)>
このエレメントは、特定のビューまたはエディター・パーツのコンテキスト・メニューに対して アクションおよび/またはメニューのグループを定義するために使用されます。
<!ATTLIST viewerContribution<!ELEMENT action (selection* , enablement?)>
このエレメントは、ユーザーが UI で起動できるアクションを定義します。
<!ATTLIST actionpush | - 通常のメニュー項目またはツール項目。 | |
radio | - ラジオ・スタイルのメニュー項目またはツール項目。同じメニューまたはツールバー・グループ内のラジオ・スタイルのアクションは、 ラジオ・セットとして動作します。初期値は、state 属性によって指定されます。 | |
toggle | - チェック・スタイル・メニュー項目またはトグル・ツール項目。初期値は、state 属性によって指定されます。 |
! | - 選択された項目が 0 | |
? | - 選択された項目が 0 または 1 | |
+ | - 選択された項目が 1 つ以上 | |
multiple, 2+ | - 選択された項目が 2 つ以上 | |
n | - 選択された項目の正確な数。 たとえば、enablesFor=" 4" では、4 つの項目が選択された場合にのみアクションが使用可能になります。 | |
* | - 任意の数の項目を選択 |
アクション拡張の使用可能性の基準は、最初は enablesFor、selection、 および enablement によって定義されます。 ただし、アクション代行はインスタンス化されると、その selectionChanged メソッド内のアクション使用可能状態を直接制御できます。
<!ELEMENT filter EMPTY>
このエレメントは、現行の選択内の各オブジェクトの属性の状態を評価するために使用されます。 選択内の各オブジェクトに指定の属性状態がある場合のみ一致。 選択内の各オブジェクトが org.eclipse.ui.IActionFilter をインプリメントするか、それに適合している必要があります。
<!ATTLIST filter<!ELEMENT menu (separator+ , groupMarker*)>
このエレメントは、新規メニューの定義に使用されます。
<!ATTLIST menu<!ELEMENT separator EMPTY>
このエレメントは、新規メニューのメニュー・セパレーターを作成するために使用されます。
<!ATTLIST separator<!ELEMENT groupMarker EMPTY>
このエレメントは、新規メニューの名前付きグループを作成するために使用されます。 これは、separator エレメントと違って、新規メニューにビジュアル表示されません。
<!ATTLIST groupMarker<!ELEMENT selection EMPTY>
このエレメントは、現行の選択を基にした、アクションの使用可能性を判別するために役立ちます。 enablement エレメントが指定されていると無視されます。
<!ATTLIST selection<!ELEMENT enablement (and | or | not | objectClass | objectState | pluginState | systemProperty)>
このエレメントは、アクションの使用可能性を定義するために使用されます。
<!ELEMENT visibility (and | or | not | objectClass | objectState | pluginState | systemProperty)>
このエレメントは、アクションの可視性を定義するために使用されます。
<!ELEMENT and (and | or | not | objectClass | objectState | pluginState | systemProperty)>
このエレメントは、2 つのサブエレメント式を評価した結果に対するブール AND 演算を表します。
<!ELEMENT or (and | or | not | objectClass | objectState | pluginState | systemProperty)>
このエレメントは、2 つのサブエレメント式を評価した結果に対するブール OR 演算を表します。
<!ELEMENT not (and | or | not | objectClass | objectState | pluginState | systemProperty)>
このエレメントは、2 つのサブエレメント式を評価した結果に対するブール NOT 演算を表します。
<!ELEMENT objectClass EMPTY>
このエレメントは、現行の選択内の各オブジェクトのクラスまたはインターフェースを評価するために使用されます。 選択内の各オブジェクトが指定されたクラスまたはインターフェースをインプリメントしている場合、式は真と評価されます。
<!ATTLIST objectClass<!ELEMENT objectState EMPTY>
このエレメントは、現行の選択内の各オブジェクトの属性の状態を評価するために使用されます。 選択内の各オブジェクトが指定された属性状態である場合、式は真と評価されます。 このタイプの式を評価するには、 選択内の各オブジェクトが org.eclipse.ui.IActionFilter インターフェースをインプリメントするか、または適合している必要があります。
<!ATTLIST objectState<!ELEMENT pluginState EMPTY>
このエレメントは、プラグインの状態を評価するために使用されます。プラグインの状態は、 installed または activated のどちらかにできます。
<!ATTLIST pluginState<!ELEMENT systemProperty EMPTY>
このエレメントは、いくつかのシステム・プロパティーの状態を評価するために使用されます。プロパティーの値は、java.lang.System から検索されます。
<!ATTLIST systemProperty
<extension point="org.eclipse.ui.popupMenus"> <objectContribution id="com.xyz.C1" objectClass="org.eclipse.core.resources.IFile" nameFilter="*.java"> <menu id="com.xyz.xyzMenu" path="additions" label="&XYZ Java Tools"> <separator name="group1"/> </menu> <action id="com.xyz.runXYZ" label="&Run XYZ Tool" style="push" menubarPath="com.xyz.xyzMenu/group1" icon="icons/runXYZ.gif" helpContextId="com.xyz.run_action_context" class="com.xyz.actions.XYZToolActionDelegate" enablesFor="1"> </action> </objectContribution> <viewerContribution id="com.xyz.C2" targetID="org.eclipse.ui.views.TaskList"> <action id="com.xyz.showXYZ" label="&Show XYZ" style="toggle" state="true" menubarPath="additions" icon="icons/showXYZ.gif" helpContextId="com.xyz.show_action_context" class="com.xyz.actions.XYZShowActionDelegate"> </action> </viewerContribution> </extension>上の例では、指定されたオブジェクト contribution アクションは単一選択 (enablesFor 属性) のみを使用可能にします。 また、選択内の各オブジェクトは、指定されたインターフェース (IFile) をインプリメントする 必要があり、Java ファイルである必要があります。このアクションは、あらかじめ作成したサブメニューに追加されます。 この contribution は、選択が要求されたいずれのビューにおいても有効となります。
一方、上記のビューアー contribution は、「タスク」ビューのコンテキスト・メニューにのみ表示され、 ビュー内の選択によって影響を受けることはありません。
フィルター・メカニズムの例を次に示します。 この場合、アクションは、終了済みで優先度の高い IMarker についてのみ表示されます。
<extension point="org.eclipse.ui.popupMenus"> <objectContribution id="com.xyz.C3" objectClass="org.eclipse.core.resources.IMarker"> <filter name="done" value="true"/> <filter name="priority" value="2"/> <action id="com.xyz.runXYZ" label="High Priority Completed Action Tool" icon="icons/runXYZ.gif" class="com.xyz.actions.MarkerActionDelegate"> </action> </objectContribution> </extension>可視性エレメントの使用に関する別の例を次に示します。
<extension point="org.eclipse.ui.popupMenus"> <viewerContribution id="com.xyz.C4" targetID="org.eclipse.ui.views.TaskList"> <visibility> <and> <pluginState id="com.xyz" value="activated"/> <systemProperty name="ADVANCED_MODE" value="true"/> </and> </visibility> <action id="com.xyz.showXYZ" label="&Show XYZ" style="push" menubarPath="additions" icon="icons/showXYZ.gif" helpContextId="com.xyz.show_action_context" class="com.xyz.actions.XYZShowActionDelegate"> </action> </viewerContribution> </extension>
上の例では、指定されたアクションはメニュー項目として表示されます。 これは、「com.xyz」プラグインがアクティブで、指定のシステム・プロパティーが true に設定されている場合に限ります。
API 情報: アクション属性 class の値は、org.eclipse.ui.IObjectActionDelegate (オブジェクト contribution の 場合)、org.eclipse.ui.IViewActionDelegate (ビューに属すコンテキスト・メニューへの contribution の場合)、 または org.eclipse.ui.IEditorActionDelegate (エディターに属すコンテキスト・メニューへの contribution の 場合) をインプリメントする Java クラスの完全修飾クラス名でなければなりません。 すべての場合において、このクラスは、プラグイン全体が実際に必要となる前に全体がロードされてしまうことのないよう、できる限り後からロードされます。
注: 下位互換性のため、org.eclipse.ui.IActionDelegate がオブジェクト contribution について インプリメントされる場合があります。
パーツ内でのコンテキスト・メニューの拡張は、ターゲット・パーツが拡張用のメニューをパブリッシュするときのみ 可能です。 これは製品の拡張性を向上させるため、強くお勧めします。 これを行うために、各パーツは IWorkbenchPartSite.registerContextMenu を呼び出すことによって 定義されるコンテキスト・メニューをパブリッシュする必要があります。 これを 1 度行えば、ワークベンチは既存のアクション拡張を自動的に挿入するようになります。
登録された各メニューには、メニュー ID が必要です。 パーツ間における整合性を保つため、すべてのパーツのインプリメンテーションにおいては、次の ストラテジーが要求されます。
ワークベンチに登録されるコンテキスト・メニューには、ID が IWorkbenchActionConstants.MB_ADDITIONS の 標準挿入ポイントも含まれなければなりません。 他のプラグインは、挿入の参照ポイントとしてこの値を使用します。 挿入ポイントは、適切な挿入ロケーションで GroupMarker をメニューに追加することにより定義できます。
コンテキスト・メニューの選択項目であるワークベンチのオブジェクトが、org.eclipse.ui.IActionFilter を 定義する場合があります。 これは、タイプ固有のフィルター操作を実行できるフィルター操作戦略です。 ワークベンチは、フィルターが IActionFilter をインプリメントするかどうかを テストすることにより、選択項目に対するフィルターを読み取ります。 これが失敗すると、ワークベンチは IAdaptable メカニズムを通してフィルターを要求します。
アクションとメニュー・ラベルは、変換されたテキスト中の選択文字の前に、 アンパーサンド ('&') 文字で指定された簡略記号をエンコードする特殊文字を含む場合があります。 アンパーサンドは XML ストリングでは許可されていないため、& 文字エンティティーを使用してください。
複数のアクションがメニューに 1 つの拡張によって与えられる場合、 アクションは plugin.xml ファイルとは逆の順序でリストされます。 この動作は、通常はすぐにわかりません。ただし、Eclipse Platform API がフリーズすると発見されます。今、この動作を変更すると、既存の動作に依存している各プラグインが混乱してしまうことになります。
selection エレメントと enablement エレメントは相互に排他的です。 サブエレメント objectClass および objectState を使用して、 enablement エレメントで selection エレメントを置き換えることができます。 以下に例を示します。
<selection class="org.eclipse.core.resources.IFile" name="*.java"> </selection>これは、以下の項目を使用して表現することができます。
<enablement> <and> <objectClass name="org.eclipse.core.resources.IFile"/> <objectState name="extension" value="java"/> </and> </enablement>
提供されるインプリメンテーション: ワークベンチ・ビューには、 いくつかのアクションにロード済みのコンテキスト・メニューが組み込まれています。 プラグインにより、これらのメニューへの contribution が可能になります。 ビューアーがこの contribution のスロットを予約しており、そのスロットが public になっている場合、 そのスロット名をパスとして使用できます。 それ以外の場合、アクションおよびサブメニューはポップアップ・メニューの最後に追加されます。
Copyright (c) 2000, 2003 IBM Corporation and others.
All rights reserved.
This program and the accompanying materials are made available under the terms of the Common Public License v1.0 which accompanies this distribution, and is available at http://www.eclipse.org/legal/cpl-v10.html