アクション・セット

org.eclipse.ui.actionSets

この拡張ポイントは、ワークベンチ・ウィンドウの共通域にメニュー、メニュー項目およびツールバー・ボタンを追加するために使用します。 これらの contribution は集合的に アクション・セット と呼ばれ、ユーザーがパースペクティブをカスタマイズすることによりワークベンチ・ウィンドウ内に表示されます。

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

enablement エレメントと visibility エレメントは同じ構文です。 どちらにも、1 つのブール式サブエレメントだけが含まれています。 最も単純なケースでは、これは 1 つの objectClassobjectStatepluginState、または systemProperty エレメントになります。 もっと複雑なケースになると、andor、および not のエレメントで結合して、1 つのブール式を構成している場合があります。 and および or エレメントの両方に、2 つのサブエレメントが含まれていなければなりません。 not エレメントには、 1 つのサブエレメントだけが含まれなければなりません。

<!ELEMENT extension (actionSet+)>

<!ATTLIST extension

point CDATA #REQUIRED

id    CDATA #IMPLIED

name  CDATA #IMPLIED>


<!ELEMENT actionSet (menu* , action*)>

<!ATTLIST actionSet

id          CDATA #REQUIRED

label       CDATA #REQUIRED

visible     (true | false)

description CDATA #IMPLIED>

このエレメントは、アクションおよび/またはメニューのグループの定義に使用されます。



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

<!ATTLIST action

id               CDATA #REQUIRED

label            CDATA #REQUIRED

accelerator      CDATA #IMPLIED

definitionId     CDATA #IMPLIED

menubarPath      CDATA #IMPLIED

toolbarPath      CDATA #IMPLIED

icon             CDATA #IMPLIED

disabledIcon     CDATA #IMPLIED

hoverIcon        CDATA #IMPLIED

tooltip          CDATA #IMPLIED

helpContextId    CDATA #IMPLIED

style            (push|radio|toggle|pulldown) "push"

state            (true | false)

pulldown         (true | false)

class            CDATA #IMPLIED

retarget         (true | false)

allowLabelUpdate (true | false)

enablesFor       CDATA #IMPLIED>

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



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



以下は、アクション・セットの例です (サブエレメントと way 属性が使用されていることに注意してください)。

    

<extension point =

"org.eclipse.ui.actionSets"

>

<actionSet id=

"com.xyz.actionSet"

label=

"My Actions"

>

<menu id=

"com.xyz.xyzMenu"

label=

"XYZ Menu"

path=

"additions"

>

<separator name=

"group1"

/>

<separator name=

"option1"

/>

</menu>

<action id=

"com.xyz.runXYZ"

label=

"&amp;Run XYZ Tool"

style=

"toggle"

state=

"false"

menubarPath=

"com.xyz.xyzMenu/group1"

icon=

"icons/runXYZ.gif"

tooltip=

"Run XYZ Tool"

helpContextId=

"com.xyz.run_action_context"

class=

"com.xyz.actions.RunXYZ"

enablesFor=

"1"

>

<selection class=

"org.eclipse.core.resources.IFile"

name=

"*.java"

/>

</action>

<action id=

"com.xyz.runABC"

label=

"&amp;Run ABC Tool"

style=

"push"

menubarPath=

"com.xyz.xyzMenu/group1"

toolbarPath=

"Normal/XYZ"

icon=

"icons/runABC.gif"

tooltip=

"Run ABC Tool"

helpContextId=

"com.xyz.run_abc_action_context"

retarget=

"true"

allowLabelUpdate=

"true"

>

<enablement>

<and>

<objectClass name=

"org.eclipse.core.resources.IFile"

/>

<not>

<objectState name=

"extension"

value=

"java"

/>

</not>

</and>

</enablement>

</action>

<action id=

"com.xyz.runDEF"

label=

"&amp;Run DEF Tool"

style=

"radio"

state=

"true"

menubarPath=

"com.xyz.xyzMenu/option1"

icon=

"icons/runDEF.gif"

tooltip=

"Run DEF Tool"

class=

"com.xyz.actions.RunDEF"

helpContextId=

"com.xyz.run_def_action_context"

>

</action>

<action id=

"com.xyz.runGHI"

label=

"&amp;Run GHI Tool"

style=

"radio"

state=

"false"

menubarPath=

"com.xyz.xyzMenu/option1"

icon=

"icons/runGHI.gif"

tooltip=

"Run GHI Tool"

class=

"com.xyz.actions.RunGHI"

helpContextId=

"com.xyz.run_ghi_action_context"

>

</action>

<action id=

"com.xyz.runJKL"

label=

"&amp;Run JKL Tool"

style=

"radio"

state=

"false"

menubarPath=

"com.xyz.xyzMenu/option1"

icon=

"icons/runJKL.gif"

tooltip=

"Run JKL Tool"

class=

"com.xyz.actions.RunJKL"

helpContextId=

"com.xyz.run_jkl_action_context"

>

</action>

</actionSet>

</extension>

上記の例で、指定された「My Actions」という名前のアクション・セットは、visible 属性が指定されていないため、各パースペクティブ内で最初は可視ではありません。

XYZ アクションは、チェック・ボックス・メニュー項目として現れます (最初はチェックマークが付いていません)。 このアクションは、選択カウントが 1 で、選択に Java ファイル・リソースが含まれている場合にのみ、使用可能になります。

ABC アクションは、メニュー内とツールバー上の両方に現れます。 このアクションは、選択に Java ファイル・リソースが含まれていない場合にのみ、使用可能になります。 このアクションはラベル再ターゲット・アクションであるため、このアクションは class 属性を提供しないことにも注意してください。

アクション DEF、GHI、および JKL は、ラジオ・ボタン・メニュー項目として現れます。 これらのアクションは、現在の選択状態とは無関係に、いつでも使用可能です。

class 属性の値は、org.eclipse.ui.IWorkbenchWindowActionDelegate または org.eclipse.ui.IWorkbenchWindowPulldownDelegate を実装するクラスの完全修飾名でなければなりません。 後者は、style 属性が値 pulldown を持つ場合に実装する必要があります。 このクラスでは、アクションを実行するのはハンドラーの役割となります。 retarget 属性が true である場合、この属性は無視されるので、指定すべきではありません。 このクラスは、プラグイン全体が実際に必要となる前に全体がロードされてしまうことがないよう、 できる限り後からロードされます。

アクション拡張の使用可能性の基準は、最初は enablesFor によって定義され、selection または enablement のいずれかによっても定義されます。 ただし、アクション代行がインスタンス化されると、その selectionChanged メソッド内のアクション使用可能状態を直接制御できます。

ワークベンチは、プラグインに代わってメニューを生成するのではないことに注意してください。 メニュー・パスは、既に存在しているメニューを参照していなければなりません。

アクションおよびメニュー・ラベルには、次の規則に従って、簡略記号をエンコードする特殊文字を含めることができます。

  1. 略号は、変換されたテキスト中の選択文字の前のアンパーサンド ('&') 文字で指定されます。 アンパーサンドは 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>

プラグインはこの拡張ポイントを使用して、新規のトップレベル・メニューを追加することができます。 また、プラグインは、 他のプラグインのアクションが提供されるようにするための名前付きグループを定義することもできます。

トップレベル・メニューは、path 属性に次の値を使用して作成されます。

path 属性を省略すると、additions メニュー・バー・グループに新規のメニューを追加することになります。

ワークベンチ・ウィンドウのデフォルト・グループは、IWorkbenchActionConstants インターフェースに定義されます。 これらの定数は、動的な contribution のコードで使用することができます。 この値は、既存のワークベンチ・メニューおよびツールバーときめ細かく融合させるために、XML ファイルにコピーすることもできます。

ワークベンチ・ウィンドウ内のさまざまなメニューおよびツールバー項目が、アルゴリズムによって定義されます。 これらのケースでは、別個のメカニズムを使用して、ウィンドウを拡張する必要があります。 例えば、新しいワークベンチ・ビューを追加すると、「パースペクティブ」メニューに新しいメニュー項目が表示されることになります。 インポート、エクスポート、および新規ウィザードの拡張機能も自動的にウィンドウに追加されます。