メニュー

org.eclipse.ui.menus

3.2

この拡張ポイントによって、プラグイン開発者が、状況表示行からコンテキスト・メニューまでのアプリケーション内のどこかに表示される、メニュー、セパレーター、論理グループおよびメニュー項目を定義することを可能にします。また、このようなコントリビューションのセットを定義できるようにします (例えば、アクション設定)。これらのアクション・セットを、エンド・ユーザーはオンにしたりオフにしたりできます。要約すれば、メニュー拡張ポイントは、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>

項目は、その置かれた場所によって、メニュー項目またはトリム項目の場合があります。項目に関連付けられたテキストとイメージは、コマンドから描画されます。



<!ELEMENT menu (location* , visibleWhen?)>

<!ATTLIST menu

id    CDATA #REQUIRED

label CDATA #IMPLIED>

メニューは、ツール項目に接続されて表示されるか、またはビュー・メニュー、コンテキスト・メニューまたはトップレベル・メニュー・バーの中のどこかで表示されます。自由に、プラグイン開発者は、すべてのビューにメニューとツールバーがあること、およびトップレベル・メニュー・バーが存在することを前提にできます。コンテキスト・メニューは、使用前に、プログラマチックに登録する必要があります (API 情報を参照してください)。

メニューにはグループしか含むことができません。



<!ELEMENT group (location*)>

<!ATTLIST group

id                CDATA #REQUIRED

separatorsVisible (true | false) "true">

論理グループ。可視 (例えば、セパレーターはその前かあとに、適宜描画されます) あるいは不可視のどちらかの場合があります。デフォルトでは、論理グループは可視です。

グループはメニュー、項目およびその他のグループを含むことができます。



<!ELEMENT widget (location* , class? , visibleWhen? , layout?)>

<!ATTLIST widget

id    CDATA #REQUIRED

class CDATA #REQUIRED>

ウィジェットへの直接アクセスが与えられたメニューまたはトリム要素。例えば、コンボ・ボックスをレンダリングするために使用されます。残念ながら、これは、ウィジェット要素がユーザー・インターフェース内で可視になった場合、プラグインのロードを生じることを意味します。 この要素はパフォーマンス上の問題の原因となる可能性があるので、注意してご使用ください。 これはまた、マクロ・サポート、スクリプトおよびその他の多くのコマンド・ベースのメカニズムのような事柄に対しても、問題の原因となります。トリムとして使用した場合、ウィジェットは UI でプラグインが可視になったときに、そのプラグインのロードのみを引き起こします。



<!ELEMENT layout EMPTY>

<!ATTLIST layout

fillMajor (true | false)

fillMinor (true | false) >

この要素は、trim ロケーション内へ追加される要素のさまざまなレイアウト・オプションを指定するために使用されます。



<!ELEMENT location (order? , (bar | part | popup))>

<!ATTLIST location

mnemonic   CDATA #IMPLIED

imageStyle CDATA #IMPLIED>

menugroupitem または widget を表示できるロケーション。この要素は、ロケーション固有の情報をコントロールするために使用されます。



<!ELEMENT bar EMPTY>

<!ATTLIST bar

type (menu|trim)

path CDATA #IMPLIED>

ロケーション内のリーフ要素。これはメニュー・バーまたはトリム・エリアである場合があります。修飾されない場合は、これは、トップレベル・メニュー・バーまたはトリムを示しています。 part 要素で修飾されている場合は、パートのメニューまたはトリムであることを示しています。



<!ELEMENT class (parameter*)>

<!ATTLIST class

class CDATA #REQUIRED>

widget 要素と dynamic 要素の両方に対する実行可能な拡張機能解析構文をサポートするクラス要素。



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

<!ATTLIST visibleWhen

checkEnabled (true | false) "false">

特定の要素の可視性をコントロールします。



<!ELEMENT part (popup | bar)>

<!ATTLIST part

id    CDATA #IMPLIED

class CDATA #IMPLIED>

ロケーション内の要素。これはロケーションを修飾し、特定のワークベンチ・パートを参照します。これはビューまたはエディターのどちらかである可能性があります。修飾では、(継承を含む) パートのクラス名を使用することも、ビューまたはエディターの ID を参照することもできます。

idclass のいずれか 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>

特定のロケーション内のメニュー、グループ、項目、またはウィジェットの位置をコントロールします。



<!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 メソッドを使用します。