ポップアップ・メニュー

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 から検索されます。



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

   

<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 になっている場合、 そのスロット名をパスとして使用できます。 それ以外の場合、アクションおよびサブメニューはポップアップ・メニューの最後に追加されます。