ポップアップ・メニュー

org.eclipse.ui.popupMenus

この拡張ポイントは、別のプラグインが所有するコンテキスト・メニューに新しいアクションを追加するために使用されます。 アクションは、特定のオブジェクト型に対して (objectContribution)、またはビューあるいはエディター・パーツの特定のコンテキスト・メニューに対して (viewerContribution) 提供することができます。objectContribution の使用時に、指定のタイプのオブジェクトが選択されたビューまたはエディター・パーツのすべてのコンテキスト・メニューに contribution が表示されます。 一方、viewerContribution の使用時には、選択に関係なく、ビューまたはエディター・パーツの指定のコンテキスト・メニューにのみ contribution が表示されます。

選択内に異種のものが混在している場合、選択内の共通する型に対してアクションの提供が登録されている場合は、可能であればそのアクションの提供が適用されます。直接のマッチングが不可能な場合、スーパークラスおよびスーパーインターフェースとのマッチングが試みられます。

選択は、名前フィルターにより、さらに制約することができます。 フィルターを使用した場合、contribution を適用するには、選択内のすべてのオブジェクトがフィルターにマッチする必要があります。

オブジェクトに提供される個々のアクションは、属性 enablesFor を使用して、そのアクションが単一、複数、または任意のいずれかの選択タイプにのみ適用されるように指定できます。

これらのフィルター・メカニズムでは不十分な場合、アクション contribution は filter メカニズムを使用することがあります。 この場合、ターゲット・オブジェクトの属性は、一連の名前と値のペアで記述されます。選択に適用される属性はタイプに固有であり、ワークベンチそれ自体のドメインの範囲外であるため、ワークベンチは、このレベルにおけるフィルタリングを実際の選択に委任します。

アクションの使用可能性と可視性は、要素 enablementvisibility をそれぞれ使用することによって定義できます。 これらの 2 つの要素にはブール式が含まれ、この式が評価されて使用可能性と可視性を決定します。

enablement 要素と visibility 要素は同じ構文です。 どちらにも、1 つのブール式サブ要素だけが含まれています。 最も単純なケースでは、これは 1 つの objectClassobjectStatepluginState、または systemProperty 要素になります。 もっと複雑なケースになると、andor、および 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? , enablement? , menu* , action*)>

<!ATTLIST objectContribution

id          CDATA #REQUIRED

objectClass CDATA #REQUIRED

nameFilter  CDATA #IMPLIED

adaptable   (true | false) "false">

この要素は、指定されたタイプのオブジェクトが選択されるビューアー・コンテキスト・メニューに対してアクションおよび/またはメニューのグループを定義するために使用されます。



<!ELEMENT viewerContribution (visibility? , menu* , action*)>

<!ATTLIST viewerContribution

id       CDATA #REQUIRED

targetID CDATA #REQUIRED>

この要素は、特定のビューまたはエディター・パーツのコンテキスト・メニューに対してアクションおよび/またはメニューのグループを定義するために使用されます。



<!ELEMENT action (selection* , enablement?)>

<!ATTLIST action

id               CDATA #REQUIRED

label            CDATA #REQUIRED

definitionId     CDATA #IMPLIED

menubarPath      CDATA #IMPLIED

icon             CDATA #IMPLIED

helpContextId    CDATA #IMPLIED

style            (push|radio|toggle|pulldown)

state            (true | false)

class            CDATA #REQUIRED

enablesFor       CDATA #IMPLIED

overrideActionId CDATA #IMPLIED

tooltip          CDATA #IMPLIED>

この要素は、ユーザーが UI で起動できるアクションを定義します。



<!ELEMENT filter EMPTY>

<!ATTLIST filter

name  CDATA #REQUIRED

value CDATA #REQUIRED>

この要素は、現在の選択内の各オブジェクトの属性の状態を評価するために使用されます。 選択内の各オブジェクトに指定の属性状態がある場合のみ一致。 選択内の各オブジェクトが org.eclipse.ui.IActionFilter を実装するか、それに適合している必要があります。



<!ELEMENT menu (separator+ , groupMarker*)>

<!ATTLIST menu

id    CDATA #REQUIRED

label CDATA #REQUIRED

path  CDATA #IMPLIED>

この要素は、新規メニューの定義に使用されます。



<!ELEMENT separator EMPTY>

<!ATTLIST separator

name CDATA #REQUIRED>

この要素は、新規メニューのメニュー・セパレーターを作成するために使用されます。



<!ELEMENT groupMarker EMPTY>

<!ATTLIST groupMarker

name CDATA #REQUIRED>

この要素は、新規メニューに名前付きグループを作成するために使用されます。 これは、separator 要素と違って、新規メニューにビジュアル表示されません。



<!ELEMENT selection EMPTY>

<!ATTLIST selection

class CDATA #REQUIRED

name  CDATA #IMPLIED>

この要素は、現在の選択を基にした、アクションの使用可能性を判別する際に役立ちます。 enablement 要素が指定されていると無視されます。



<!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)>

この要素は、サブ要素式を評価した結果に対するブール NOT 演算を表します。



<!ELEMENT objectClass EMPTY>

<!ATTLIST objectClass

name CDATA #REQUIRED>

この要素は、現在の選択内の各オブジェクトのクラスまたはインターフェースを評価するために使用されます。 選択内の各オブジェクトが指定されたクラスまたはインターフェースを実装している場合、式は真と評価されます。



<!ELEMENT objectState EMPTY>

<!ATTLIST objectState

name  CDATA #REQUIRED

value CDATA #REQUIRED>

この要素は、現在の選択内の各オブジェクトの属性の状態を評価するために使用されます。 選択内の各オブジェクトが指定された属性状態である場合、式は真と評価されます。 このタイプの式を評価するには、選択内の各オブジェクトが org.eclipse.ui.IActionFilter インターフェースを実装するか、またはそれに適合している必要があります。



<!ELEMENT pluginState EMPTY>

<!ATTLIST pluginState

id    CDATA #REQUIRED

value (installed|activated) "installed">

この要素は、プラグインの状態を評価するために使用されます。 プラグインの状態は、installed (OSGi の「resolved」の概念と等価) または activated (OSGi の「active」の概念と等価) のいずれかです。



<!ELEMENT systemProperty EMPTY>

<!ATTLIST systemProperty

name  CDATA #REQUIRED

value CDATA #REQUIRED>

この要素は、いくつかのシステム・プロパティーの状態を評価するために使用されます。 プロパティーの値は、java.lang.System から検索されます。



<!ELEMENT enablement (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>

汎用ルート要素です。 この要素を拡張ポイントの内部で使用すると、enablement 式を定義できます。 enablement 式の子は、AND 演算子を使用して結合されます。



<!ELEMENT not (not | and | or | instanceof | test | systemTest | equals | count | with | resolve | adapt | iterate)>

この要素は、サブ要素式を評価した結果に対する NOT 演算を表します。



<!ELEMENT and (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>

この要素は、サブ要素式すべてを評価した結果に対する AND 演算を表します。



<!ELEMENT or (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>

この要素は、サブ要素式すべてを評価した結果に対する OR 演算を表します。



<!ELEMENT instanceof EMPTY>

<!ATTLIST instanceof

value CDATA #REQUIRED>

この要素は、フォーカスされているオブジェクトの instanceof 検査を実行するために使用されます。 オブジェクトの型が、属性値で指定されている型のサブタイプの場合、この式は EvaluationResult.TRUE を戻します。これ以外の場合は、EvaluationResult.FALSE を戻します。



<!ELEMENT test EMPTY>

<!ATTLIST test

property CDATA #REQUIRED

args     CDATA #IMPLIED

value    CDATA #IMPLIED>

この要素は、フォーカスされているオブジェクトのプロパティー状態を評価するために使用されます。 テスト可能なプロパティーのセットは、プロパティー・テスターの拡張ポイントを使用して拡張することができます。 実際のテストを実行するプロパティー・テスターがまだロードされていない場合、test 式は EvaluationResult.NOT_LOADED を戻します。



<!ELEMENT systemTest EMPTY>

<!ATTLIST systemTest

property CDATA #REQUIRED

value    CDATA #REQUIRED>

System.getProperty メソッドを呼び出してシステム・プロパティーをテストし、その結果を、 value 属性によって指定された値と比べてください。



<!ELEMENT equals EMPTY>

<!ATTLIST equals

value CDATA #REQUIRED>

この要素は、フォーカスされているオブジェクトの等号検査を実行するために使用されます。 オブジェクトが、属性値によって提供された値と等しい場合、この式は EvaluationResult.TRUE を戻します。 これ以外の場合は、EvaluationResult.FALSE を戻します。



<!ELEMENT count EMPTY>

<!ATTLIST count

value CDATA #REQUIRED>

この要素は、コレクション内の要素の数をテストするために使用されます。



<!ELEMENT with (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>

<!ATTLIST with

variable CDATA #REQUIRED>

この要素は、すべての子要素がインスペクション対象であるオブジェクトを、指定の変数で参照されているオブジェクトに変更します。 変数が解決できない場合、式は、評価時に ExpressionException をスローします。 with 式の子は、AND 演算子を使用して結合されます。



<!ELEMENT resolve (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>

<!ATTLIST resolve

variable CDATA #REQUIRED

args     CDATA #IMPLIED>

この要素は、すべての子要素がインスペクション対象であるオブジェクトを、指定の変数で参照されているオブジェクトに変更します。 変数が解決できない場合、式は、評価時に ExpressionException をスローします。 with 式の子は、AND 演算子を使用して結合されます。



<!ELEMENT adapt (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>

<!ATTLIST adapt

type CDATA #REQUIRED>

この要素は、フォーカスされているオブジェクトを、属性型で指定されている型に適合させるために使用されます。 アダプターまたは参照される型がまだロードされていない場合、式は「ロードされていない」を戻します。 型名が全く存在しない場合、評価中に ExpressionException がスローされます。 adapt 式の子は、AND 演算子を使用して結合されます。



<!ELEMENT iterate (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>

<!ATTLIST iterate

operator (or|and) >

この要素は、java.util.Collection 型の変数を繰り返すために使用されます。 フォーカスされているオブジェクトの型が java.util.Collection ではない場合、式の評価時に ExpressionException がスローされます。



ポップアップ・メニュー拡張ポイントの例を以下に示します。

   

<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=

"&amp;XYZ Java Tools"

>

<separator name=

"group1"

/>

</menu>

<action id=

"com.xyz.runXYZ"

label=

"&amp;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"

/>

</objectContribution>

<viewerContribution id=

"com.xyz.C2"

targetID=

"org.eclipse.ui.views.TaskList"

>

<action id=

"com.xyz.showXYZ"

label=

"&amp;Show XYZ"

style=

"toggle"

state=

"true"

menubarPath=

"additions"

icon=

"icons/showXYZ.gif"

helpContextId=

"com.xyz.show_action_context"

class=

"com.xyz.actions.XYZShowActionDelegate"

/>

</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=

"&amp;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 に設定されている場合に限ります。

action 属性 class の値は、オブジェクト・コントリビューションの場合は org.eclipse.ui.IObjectActionDelegate、ビューに属するコンテキスト・メニューへのコントリビューションの場合は org.eclipse.ui.IViewActionDelegate、エディターに属するコンテキスト・メニューへのコントリビューションの場合は org.eclipse.ui.IEditorActionDelegate をそれぞれ実装する Java クラスの完全修飾クラス名である必要があります。 すべての場合において、このクラスは、プラグイン全体が実際に必要となる前に全体がロードされてしまうことのないよう、できる限り後からロードされます。

注: 下位互換性のため、org.eclipse.ui.IActionDelegate がオブジェクト contribution について実装される場合があります。

パーツ内でのコンテキスト・メニューの拡張は、ターゲット・パーツが拡張用のメニューをパブリッシュするときのみ可能です。 これは製品の拡張性を向上させるため、強くお勧めします。 これを行うために、各パーツは IWorkbenchPartSite.registerContextMenu を呼び出すことによって定義されるコンテキスト・メニューをパブリッシュする必要があります。 これを一度行えば、ワークベンチは既存のアクション拡張を自動的に挿入するようになります。

登録された各メニューには、メニュー ID が必要です。 パーツ間における整合性を保つため、すべてのパーツの実装においては、次のストラテジーが要求されます。

ワークベンチに登録されるコンテキスト・メニューには、ID が IWorkbenchActionConstants.MB_ADDITIONS の標準挿入ポイントも含まれなければなりません。 他のプラグインは、挿入の参照ポイントとしてこの値を使用します。 挿入ポイントは、適切な挿入ロケーションで GroupMarker をメニューに追加することにより定義できます。

コンテキスト・メニューの選択項目であるワークベンチのオブジェクトが、org.eclipse.ui.IActionFilter を定義する場合があります。 これは、タイプ固有のフィルタリングを実行できるフィルタリング戦略です。ワークベンチは、フィルターが IActionFilter を実装するかどうかをテストすることにより、選択項目に対するフィルターを読み取ります。 これが失敗すると、ワークベンチは IAdaptable メカニズムを通してフィルターを要求します。

アクションとメニュー・ラベルは、変換されたテキスト中の選択文字の前に、アンパーサンド ('&') 文字で指定された簡略記号をエンコードする特殊文字を含む場合があります。 アンパーサンドは XML ストリングでは許可されていないため、&amp; 文字エンティティーを使用してください。

複数のアクションがメニューに 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>

ワークベンチ・ビューには、いくつかのアクションをロード済みの組み込みコンテキスト・メニューがあります。 プラグインにより、これらのメニューへのコントリビュートが可能になります。 ビューアーがこのコントリビューションのスロットを予約しており、そのスロットが public になっている場合、そのスロット名をパスとして使用できます。 それ以外の場合、アクションおよびサブメニューはポップアップ・メニューの最後に追加されます。