選択内に異種のものが混在している場合、選択内の共通する型に対してアクションの提供が登録されている場合は、可能であればそのアクションの提供が適用されます。直接のマッチングが不可能な場合、スーパークラスおよびスーパーインターフェースとのマッチングが試みられます。
選択は、名前フィルターにより、さらに制約することができます。 フィルターを使用した場合、contribution を適用するには、選択内のすべてのオブジェクトがフィルターにマッチする必要があります。
オブジェクトに提供される個々のアクションは、属性 enablesFor
を使用して、そのアクションが単一、複数、または任意のいずれかの選択タイプにのみ適用されるように指定できます。
これらのフィルター・メカニズムでは不十分な場合、アクション 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? , 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 で起動できるアクションを定義します。
push | - 通常のメニュー項目またはツール項目。 | |
radio | - ラジオ・スタイルのメニュー項目またはツール項目。 同じメニューまたはツールバー・グループ内のラジオ・スタイルのアクションは、ラジオ・セットとして動作します。 初期値は、state 属性によって指定されます。 | |
toggle | - チェック・スタイル・メニュー項目またはトグル・ツール項目。 初期値は、state 属性によって指定されます。 | |
pulldown | - カスケード・スタイル・メニュー項目。 |
! | - 選択された項目が 0 | |
? | - 選択された項目が 0 または 1 | |
+ | - 選択された項目が 1 つ以上 | |
multiple, 2+ | - 選択された項目が 2 つ以上 | |
n | - 選択された項目の正確な数。 例えば、enablesFor=" 4" では、4 つの項目が選択された場合にのみアクションが使用可能になります。 | |
* | - 任意の数の項目を選択 |
アクション拡張の使用可能性の基準は、最初は enablesFor、selection、および enablement によって定義されます。 ただし、アクション委譲はインスタンス化されると、その selectionChanged メソッド内のアクション使用可能状態を直接制御できます。
<!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 がスローされます。
上の例では、指定されたオブジェクト contribution アクションは単一選択 (enablesFor 属性) のみを使用可能にします。 また、選択内の各オブジェクトは、指定されたインターフェース (IFile) を実装する必要があり、Java ファイルである必要があります。 このアクションは、あらかじめ作成したサブメニューに追加されます。 この contribution は、選択が要求されたいずれのビューにおいても有効となります。<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"
/>
</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"
/>
</viewerContribution>
</extension>
一方、上記のビューアー 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 に設定されている場合に限ります。
注: 下位互換性のため、org.eclipse.ui.IActionDelegate がオブジェクト contribution について実装される場合があります。
パーツ内でのコンテキスト・メニューの拡張は、ターゲット・パーツが拡張用のメニューをパブリッシュするときのみ可能です。 これは製品の拡張性を向上させるため、強くお勧めします。 これを行うために、各パーツは IWorkbenchPartSite.registerContextMenu を呼び出すことによって定義されるコンテキスト・メニューをパブリッシュする必要があります。 これを一度行えば、ワークベンチは既存のアクション拡張を自動的に挿入するようになります。
登録された各メニューには、メニュー 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>
Copyright (c) 2000, 2005 IBM Corporation and others.
All rights reserved.
This program and the accompanying materials are made
available under the terms of the Eclipse Public License v1.0 which accompanies
this distribution, and is available at
http://www.eclipse.org/legal/epl-v10.html