この拡張ポイントによって、プラグイン開発者が、状況表示行からコンテキスト・メニューまでのアプリケーション内のどこかに表示される、メニュー、セパレーター、論理グループおよびメニュー項目を定義することを可能にします。また、このようなコントリビューションのセットを定義できるようにします (例えば、アクション設定)。これらのアクション・セットを、エンド・ユーザーはオンにしたりオフにしたりできます。要約すれば、メニュー拡張ポイントは、Eclipse 内のすべてのメニューまたはトリム・エリアにコントリビュートするための、(アイコン以外の) すべてのプレゼンテーション要素を含みます。
この拡張ポイント内のすべての要素に、固有 ID が与えられます。これにより、要素の再記述なしで、別の場所でこれらの要素を参照できます。例えば、アクション・セットの配列または定義のために、ID が必要な場合があります。また、これにより、サード・パーティーのプラグイン開発者が、必要に応じてインターフェース内の新規ロケーションにこれらの要素を配置することが可能になります。
注: 3.2 では、実装されているこの拡張メカニズムのパートのみが、「トリム」コントリビューションに関連したパートです。項目、メニュー、ツールバー、状況表示行項目を追加しようとすると、ノーオペレーションとして機能します。
<!ELEMENT extension (item* , menu* , group* , widget*)>
<!ATTLIST extension
point CDATA #REQUIRED
id CDATA #IMPLIED
name CDATA #IMPLIED>
<!ELEMENT item (parameter* , location* , visibleWhen?)>
<!ATTLIST item
id CDATA #REQUIRED
commandId CDATA #REQUIRED
menuId CDATA #IMPLIED>
項目は、その置かれた場所によって、メニュー項目またはトリム項目の場合があります。項目に関連付けられたテキストとイメージは、コマンドから描画されます。
org.eclipse.ui
によってコントリビュートされた項目が、org.eclipse.ui.item1
という名前になる可能性があります。
<!ELEMENT menu (location* , visibleWhen?)>
<!ATTLIST menu
id CDATA #REQUIRED
label CDATA #IMPLIED>
メニューは、ツール項目に接続されて表示されるか、またはビュー・メニュー、コンテキスト・メニューまたはトップレベル・メニュー・バーの中のどこかで表示されます。自由に、プラグイン開発者は、すべてのビューにメニューとツールバーがあること、およびトップレベル・メニュー・バーが存在することを前提にできます。コンテキスト・メニューは、使用前に、プログラマチックに登録する必要があります (API 情報を参照してください)。
メニューにはグループしか含むことができません。
org.eclipse.ui
によってコントリビュートされたメニューが、org.eclipse.ui.menu1
という名前になる可能性があります。
<!ATTLIST group
id CDATA #REQUIRED
separatorsVisible (true | false) "true">
論理グループ。可視 (例えば、セパレーターはその前かあとに、適宜描画されます) あるいは不可視のどちらかの場合があります。デフォルトでは、論理グループは可視です。
グループはメニュー、項目およびその他のグループを含むことができます。
org.eclipse.ui
によってコントリビュートされたグループが、org.eclipse.ui.group1
という名前になる可能性があります。
<!ELEMENT widget (location* , class? , visibleWhen? , layout?)>
<!ATTLIST widget
id CDATA #REQUIRED
class CDATA #REQUIRED>
ウィジェットへの直接アクセスが与えられたメニューまたはトリム要素。例えば、コンボ・ボックスをレンダリングするために使用されます。残念ながら、これは、ウィジェット要素がユーザー・インターフェース内で可視になった場合、プラグインのロードを生じることを意味します。 この要素はパフォーマンス上の問題の原因となる可能性があるので、注意してご使用ください。 これはまた、マクロ・サポート、スクリプトおよびその他の多くのコマンド・ベースのメカニズムのような事柄に対しても、問題の原因となります。トリムとして使用した場合、ウィジェットは UI でプラグインが可視になったときに、そのプラグインのロードのみを引き起こします。
org.eclipse.ui
によってコントリビュートされたウィジェットが、org.eclipse.ui.widget1
という名前になる可能性があります。IWorkbenchWidget
を実装する必要があります。クライアントは、デフォルトの実装 AbstractWorkbenchTrimWidget
の使用を選択することができます。この実装は、'init' メソッドを扱い、getWorkbenchWindow
メソッドで使用するために結果をキャッシュします。
<!ELEMENT layout EMPTY>
<!ATTLIST layout
fillMajor (true | false)
fillMinor (true | false) >
この要素は、trim
ロケーション内へ追加される要素のさまざまなレイアウト・オプションを指定するために使用されます。
false
です。
false
です。
<!ELEMENT location (order? , (bar | part | popup))>
<!ATTLIST location
mnemonic CDATA #IMPLIED
imageStyle CDATA #IMPLIED>
menu
、group
、item
または widget
を表示できるロケーション。この要素は、ロケーション固有の情報をコントロールするために使用されます。
<!ELEMENT bar EMPTY>
<!ATTLIST bar
type (menu|trim)
path CDATA #IMPLIED>
ロケーション内のリーフ要素。これはメニュー・バーまたはトリム・エリアである場合があります。修飾されない場合は、これは、トップレベル・メニュー・バーまたはトリムを示しています。
part
要素で修飾されている場合は、パートのメニューまたはトリムであることを示しています。
menu
または trim
である場合があります。メニューへコントリビュートする場合、項目は、なんらかのウィジェット構造の子になります。一般に、これは、ウィジェット要素を使用することにそれほど意義がないということであり、この項目のコマンドのためのアイコンが厳密には必要でないことを意味します。デフォルト値は menu
です。
trim
へコントリビュートする場合、そのバーは一般的にコマンドまたはアイコンを必要とせず、トリム情報を表示するウィジェットによって埋められます。
トリム内で、ワークベンチは 5 つの一般グループを定義し、これはウィンドウのさまざまな位置に対応します。
vertical1
からワークベンチの反対側に置かれます。
'/'
を使用します。
<!ATTLIST class
class CDATA #REQUIRED>
widget
要素と dynamic
要素の両方に対する実行可能な拡張機能解析構文をサポートするクラス要素。
IExecutableExtension
としてロードするためのクラス。
<!ELEMENT visibleWhen (not | or | and | instanceof | test | systemTest | equals | count | with | resolve | adapt | iterate)>
<!ATTLIST visibleWhen
checkEnabled (true | false) "false">
特定の要素の可視性をコントロールします。
true
に設定されている場合、サブ要素はありません。これは単にコマンドの有効状態をチェックし、コマンドが使用可能な場合、対応する要素を可視にします。
<!ATTLIST part
id CDATA #IMPLIED
class CDATA #IMPLIED>
ロケーション内の要素。これはロケーションを修飾し、特定のワークベンチ・パートを参照します。これはビューまたはエディターのどちらかである可能性があります。修飾では、(継承を含む) パートのクラス名を使用することも、ビューまたはエディターの ID を参照することもできます。
id
と class
のいずれか 1 つのみ、指定できます。
<!ELEMENT parameter EMPTY>
<!ATTLIST parameter
name CDATA #REQUIRED
value CDATA #REQUIRED>
実行可能な拡張機能またはコマンドのいずれかへのパラメーター -- 拡張機能内のどこに表示されるかによります。
<!ELEMENT order EMPTY>
<!ATTLIST order
position (start|end|before|after)
relativeTo CDATA #IMPLIED>
特定のロケーション内のメニュー、グループ、項目、またはウィジェットの位置をコントロールします。
この属性は次の値を受け入れます:
start
(コンテナーの先頭に要素を配置)、end
(コンテナーの最後に要素を配置)、after
(その ID が
ref
と一致する兄弟要素のあとに要素を配置)、および
before
(その ID が ref
と一致する兄弟要素の前に要素を配置)。相対配列は、メニュー要素のいずれのタイプにも適用できます。
競合の発生時には、Eclipse は任意の配列を選択します。競合の発生時に保証されるのは、以下が保持されている限り、配列が同じに保たれることだけです。
position
が before
または after
である場合、必須です。
<!ELEMENT popup EMPTY>
<!ATTLIST popup
id CDATA #IMPLIED
path CDATA #IMPLIED>
ロケーションの一部。メニュー、グループ、項目またはウィジェットがポップアップ・メニューに表示されることを示します。
<!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 がスローされます。
基本のメニュー定義は以下のようです。
<menu id=
"com.mycompany.myplugin.projection"
label=
"%Folding.label"
>
<location mnemonic=
"%Folding.label.mnemonic"
>
<part id=
"AntEditor"
>
<popup id=
"#RulerContext"
path=
"rest"
/>
</part>
</location>
</menu>
この例では、プラグイン開発者は、特定の型をサブクラス化するか、または実装する、すべてのパーツにコントリビュートします。これにより、例えば、いくつかのコントリビューションがすべてのテキスト・エディターに追加されることが可能になります。
<menu id=
"com.mycompany.myplugin.textEditorMenu"
label=
"Text Commands"
>
<location mnemonic=
"X"
>
<part class=
"AbstractTextEditor"
>
<popup id=
"#RulerContext"
path=
"rest"
/>
</part>
</location>
</menu>
ヘルプをメニューに関連付けることが可能です。
<menu id=
"com.mycompany.myplugin.RunWithConfigurationAction"
label=
"Run With Configuration"
helpContextId=
"run_with_configuration_context"
>
<location>
<bar />
</location>
</menu>
メニュー内で、論理グループを定義することが可能です。これらの論理グループは、可視 (例えば、セパレーターはその前かあとに、適宜描画されます) あるいは不可視のどちらかの場合があります。デフォルトでは、論理グループは可視です。
<group id=
"com.mycompany.myplugin.stepGroup"
>
<location>
<bar path=
"org.eclipse.ui.run"
/>
</location>
</group>
<group id=
"com.mycompany.myplugin.stepIntoGroup"
separatorsVisible=
"false"
>
<location>
<bar path=
"org.eclipse.ui.run"
/>
</location>
</group>
複数のロケーションに、メニュー、グループ、項目およびウィジェットを配置することが可能です。
<item id=
"com.mycompany.myplugin.ToggleStepFilters"
commandId=
"com.mycompany.myplugin.ToggleStepFilters"
>
<location mnemonic=
"%mnemonic"
>
<bar path=
"org.eclipse.ui.run/emptyStepGroup"
/>
</location>
<location>
<part id=
"org.eclipse.debug.ui.DebugView"
>
<bar type=
"trim"
path=
"renderGroup"
/>
</part>
</location>
<location mnemonic=
"%mnemonic"
>
<part id=
"org.eclipse.debug.ui.DebugView"
>
<popup path=
"renderGroup"
/>
</part>
</location>
</item>
ポップアップ要素が ID も親のパート要素もなしで指定された場合は、ワークベンチで登録済みのすべてのコンテキスト・メニューに適用されます。これは古いオブジェクト・コントリビューションの振る舞いに類似しています。同様に、ID を持つトップレベル・ポップアップ要素は、特定の名前で登録されたすべてのコンテキスト・メニューに影響します。
<item id=
"com.mycompany.myplugin.ObjectContribution"
commandId=
"com.mycompany.myplugin.ObjectContribution"
>
<location>
<popup path=
"additions"
/>
</location>
</item>
項目の可視性をコントロールしたい場合があります。通常は、メニューおよびツールバーのレイアウトで安定度を維持することが望ましいのですが、すぐには関係のない項目を非表示にしたい場合もあります。これは特に、スペースが限定されているコンテキスト・メニューにおいて当てはまります。このケースでは、visibleWhen
要素を定義します。この要素は、ハンドラー拡張ポイントで定義された activeWhen
要素および enabledWhen
要素とほとんど同一です。
<item id=
"com.mycompany.myplugin.ConvertToWatchExpression"
commandId=
"com.mycompany.myplugin.ConvertToWatchExpression"
>
<location mnemonic=
"%mnemonic"
>
<part id=
"org.eclipse.debug.ui.DebugView"
>
<popup path=
"additions"
/>
</part>
</location>
<visibleWhen>
<with variable=
"selection"
>
<iterate operator=
"and"
>
<not>
<instanceof value=
"IWatchExpression"
/>
</not>
<instanceof value=
"IExpression"
/>
</iterate>
</with>
</visibleWhen>
</item>
もっとも一般的なケースは、そのハンドラーが使用可能のときになにかを単に可視にすることです。これは、なんらかの syntactic sugar (構文糖) で処理されます。
visibleWhen
要素に checkEnabled
属性があります。
<item id=
"com.mycompany.myplugin.compareWithPatch"
commandId=
"com.mycompany.myplugin.compareWithPatch"
>
<location mnemonic=
"%mnemonic"
>
<part id=
"MyPart"
>
<popup path=
"additions"
/>
</part>
</location>
<visibleWhen checkEnabled=
"true"
/>
</item>
コマンドと関連付けられているどの項目も、パラメーター値を含むことができます。与えられた ID のパラメーターが定義されていない場合は、これはエラーです。項目がコマンドを持っていない場合、これもエラーです。
<item id=
"com.mycompany.myplugin.RunHistory"
commandId=
"com.mycompany.myplugin.RunHistory"
>
<location>
<bar path=
"org.eclipse.ui.run"
/>
</location>
<parameter name=
"index"
value=
"1"
/>
</item>
また、相対配列を指定することも可能です。これは、ロケーション要素上の order 属性を使用することによって行います。
order 属性は次の値を受け入れます:
start
(コンテナーの先頭に要素を配置)、end (コンテナーの最後に要素を配置)、after
(その ID が ref
と一致する兄弟要素のあとに要素を配置)、および before
(その ID が ref
と一致する兄弟要素の前に要素を配置)。相対配列は、メニュー要素のいずれのタイプにも適用できます。
<item id=
"com.mycompany.myplugin.MyFirstItem"
commandId=
"com.mycompany.myplugin.MyFirstCommand"
>
<location>
<order position=
"start"
/>
<bar path=
"org.eclipse.ui.run"
/>
</location>
</item>
<item id=
"com.mycompany.myplugin.MySecondItem"
commandId=
"com.mycompany.myplugin.MySecondCommand"
>
<location>
<order position=
"after"
relativeTo=
"com.mycompany.myplugin.MyFirstItem"
/>
<bar path=
"org.eclipse.ui.run"
/>
</location>
</item>
ウィジェットへの直接アクセスが必要な場合 (例えば、コンボ・ボックスのレンダリングの場合)、widget
要素を使用することができます。残念ながら、これは、ウィジェット要素がユーザー・インターフェース内で可視になった場合、プラグインのロードを生じることを意味します。
<widget id=
"com.mycompany.myplugin.MyComboBoxSimple"
class=
"com.mycompany.myplugin.MyComboBox"
>
<location>
<bar type=
"trim"
path=
"myGroup"
/>
</location>
</widget>
<widget id=
"com.mycompany.myplugin.MyComboBoxParameterized1"
class=
"com.mycompany.myplugin.MyComboBox:a,b,c"
>
<location>
<bar type=
"trim"
path=
"myGroup"
/>
</location>
</widget>
<widget id=
"com.mycompany.myplugin.MyComboBoxParameterized2"
>
<class class=
"com.mycompany.myplugin.MyComboBox"
>
<parameter name=
"list"
value=
"a,b,c"
/>
<parameter name=
"selected"
value=
"c"
/>
<parameter name=
"editable"
value=
"false"
/>
</class>
<location>
<bar type=
"trim"
path=
"myGroup"
/>
</location>
</widget>
また、ウィジェットを使用して、ワークベンチ・トリムへコントリビュートすることもできます。以下の例は、デフォルトで、状況表示行トリムのすぐあと (つまり、ワークベンチ・ウィンドウの下部) に置かれる新規の「HeapStatus」ウィジェットを定義します。事前定義グループの詳細は、「bar」要素の説明を参照してください。
トリム「グループ」はその他のトリム・エリアに再配置できることに注意してください。ロケーション情報の relativeTo
は、新規のトリムのロケーションを判別するとき、参照されるグループがそのデフォルトの位置にあると仮定します。一般に、このタイプのコントリビューターは、トリム要素を、他のトリム要素とは独立して再配置できるように、自身のグループを作成して新規ウィジェットをホストすることが予想されます。これに対する注意すべき 1 つの例外は、「状況」グループです。
<extension point=
"org.eclipse.ui.menus"
>
<group id=
"TestTrimAPI.heapStatusGroup"
separatorsVisible=
"true"
>
<location>
<bar type=
"trim"
/>
<order position=
"after"
relativeTo=
"status"
/>
</location>
</group>
<widget class=
"HeapStatusWidget"
id=
"TestTrimAPI.HeapStatus"
>
<location>
<bar path=
"heapStatusGroup"
type=
"trim"
/>
</location>
<layout fillMajor=
"false"
fillMinor=
"true"
/>
</widget>
</extension>
IWorkbenchPartSite.registerContextMenu
メソッドを使用します。
Copyright (c) 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