アクション・セット
ID: org.eclipse.ui.actionSets
説明: この拡張ポイントは、ワークベンチ・ウィンドウの共通域にメニュー項目および
ツールバー・ボタンを追加するために使用します。
これらの contribution は集合的に アクション・セット と呼ばれ、ユーザーの設定により
ワークベンチ・ウィンドウ内に表示されます。
構成マークアップ:
<!ELEMENT actionSet (menu)* (action)* (description?)>
<!ATTLIST actionSet
id CDATA
#REQUIRED
label CDATA #REQUIRED
visible (true
| false) #IMPLIED
>
<!ELEMENT description (#PCDATA)>
-
id - このアクション・セットの識別に使用する固有名
-
label - ワークベンチ・ウィンドウ内で使用される、このアクション・セットを表す変換可能な名前。
-
visible - すべてのパースペクティブ内でアクション・セットを最初から可視にするかどうかを
指示するオプション属性。
このオプションは、カスタマイズされていない新規のパースペクティブをユーザーが開くときにのみ、
要求を受け入れます。
ユーザーは、「パースペクティブのカスタマイズ・ダイアログ」から、このオプションを
オーバーライドできます。
-
description - アクション・セットの簡潔な説明テキストを本文に含むオプションのサブエレメント。
<!ELEMENT menu (separator)+ (groupMarker)*>
<!ATTLIST menu
id
CDATA #REQUIRED
label
CDATA #REQUIRED
path
CDATA #IMPLIED
>
-
id - このメニューの参照に使用可能な固有 ID。
-
label - 新規メニューのテキスト・ラベル。ラベルには、略号情報を含む必要があります。
-
path - メニュー・バーのルートから開始するメニューの位置。
省略されると、メニューはメニュー・バーの「ウィンドウ」メニューの前に追加されます。
パス内の各トークンは、パス内の最後のメニューにある名前付きグループを表す最後のトークンを除き、
ワークベンチの既存のメニューを参照する必要があります。
<!ELEMENT separator EMPTY>
<!ATTLIST separator
name
CDATA #REQUIRED
>
name - 後でアクション・パスの最後のトークンとして参照が可能な区切り文字の名前。
区切り文字は、アクションおよびサブメニューの追加先にすることのできる名前付きグループとして
使用することができます。
<!ELEMENT groupMarker EMPTY>
<!ATTLIST groupMarker
name
CDATA #REQUIRED
>
name - 後でアクション・パスの最後のトークンとして参照が可能なグループ・マーカーの名前。
<!ELEMENT action (selection)* (enablement)?>
<!ATTLIST action
id
NMTOKEN #REQUIRED
label
CDATA #REQUIRED
accelerator
CDATA #IMPLIED
definitionId
CDATA #IMPLIED
menubarPath
CDATA #IMPLIED
toolbarPath
CDATA #IMPLIED
icon
CDATA #IMPLIED
disabledIcon
CDATA #OPTIONAL
hoverIcon
CDATA #OPTIONAL
tooltip
CDATA #IMPLIED
helpContextId
CDATA #IMPLIED
state
(true | false) #IMPLIED
pulldown
(true | false) #IMPLIED
class
CDATA #OPTIONAL
retarget
(true | false) #OPTIONAL
allowLabelUpdate
(true | false) #OPTIONAL
enablesFor
CDATA #IMPLIED
>
-
id - このアクションの参照として使用可能な固有 ID。
-
label - コンテキストに応じて使用される変換可能な名前。
これは、メニュー内ではメニュー・テキストとして使用されます。
ツールバーでは、ボタン・ラベルとして使用されます。
ラベルには JFace エンコードの略号およびアクセラレーター情報を含むことができます (例を参照)。
-
accelerator - アクション用にアクセラレーターのキー・コードを指定するために使用する整数。
これは、0 以上の SWT キー修飾子マスクのビット単位 OR (すなわち SWT.CTRL または SWT.ALT)、および
1 つの文字コードから生じる整数値です。
たとえば、Ctrl+Z は SWT.CTRL | 'Z' = (1<<18)|'Z' = 262234 を使用します。
-
definitionId - アクション定義で指定される ID。
アクション・セットがキー・バインディング・サービスによってアクセラレーターを指定する場合のみ必要です。
アクション定義および
アクセラレーター・セット拡張ポイントを参照してください。
-
menubarPath - メニュー・バーのアクションの位置を指定するスラッシュ ('/') で区切られたパス。
最後のものを除くパス内の各トークンは、階層内の既存のメニューの有効な ID を表す必要があります。
最後のトークンは、アクションの追加先となる名前付きの区切り文字グループを表します。
パスを省略した場合、メニュー・バーにアクションは現れません。
-
toolbarPath - ツールバー内のアクションの位置を指定するスラッシュ ('/') で区切られたパス。
最初のトークンはツールバー ID を表し ("Normal" はデフォルトのツールバー)、2 番目のトークンは
ツールバー内の名前付きグループとなります。
グループがツールバーに存在しない場合は、グループが作成されます。
toolbarPath を省略した場合、ツールバーにアクションは現れません。
-
icon - コンテキスト内のアクションをビジュアルに表すためのアイコンの相対パス。
これを省略した場合、ツールバーにアクションが現れると、ワークベンチでは代わりのアイコンが
使用されます。
パスは、提供元のプラグインの plugin.xml ファイルの位置に対する相対パスとなります。
アイコンはツールバーには表示されますが、メニューには表示されません。
使用可能になったアクションは、メニューに hoverIcon で表示されます。
-
disabledIcon - アクションが使用不可なときに、コンテキスト内のアクションをビジュアルに
表すためのアイコンの相対パス。
省略されると、標準アイコンは単にぼかし表示されます。
パスは、提供元のプラグインの plugin.xml ファイルの位置に対する相対パスとなります。
使用不可のアイコンはツールバーには表示されますが、メニューには表示されません。
メニューにある使用不可のアクションのアイコンは、OS によって提供されます。
-
hoverIcon - マウスがアクション上にあるときに、コンテキスト内のアクションをビジュアルに
表すためのアイコンの相対パス。
省略した場合は、標準アイコンが使用されます。
パスは、提供元のプラグインの plugin.xml ファイルの位置に対する相対パスとなります。
-
tooltip - ツールバーにアクションが現れる場合の、ツールのヒント・テキストの値。
アクションが現れない場合、これは無視されます。
-
helpContextId - このアクションのヘルプ・コンテキスト ID を示す固有 ID。
アクションがメニュー項目として現れる場合、メニュー項目を強調表示しながら F1 キーを押すと、その
コンテキスト ID のヘルプが表示されます。
-
state - アクションをトグル・タイプとするよう指示するオプション属性。
メニューに追加する際、これはチェック・ボックスとして現れます。
ツールバーに追加すると、トグル・ボタンとなります。
定義された属性値は、初期状態として使用されます (true または false)。
この属性は、pulldown とは相互に排他的です。
-
pulldown - アクションにプルダウン・メニューを追加するよう指示するオプション属性。
ツールバーにアクションが現れ、属性値が true の場合、アクションの隣にプルダウン・メニューが
表示されます。
メニューにアクションが現れる場合、この属性は無視されます。
この属性は、state とは相互に排他的です。
-
class - org.eclipse.ui.IWorkbenchWindowActionDelegate または
org.eclipse.ui.IWorkbenchWindowPulldownDelegate をインプリメントするクラスの完全修飾名。
後者は、pulldown が true の場合にインプリメントする必要があります。
retarget 属性が true の場合は、この属性は提供されません。
-
retarget - この属性が true の場合は、retarget (グローバル) アクションが作成されます。
パーツは、このアクションの ID を使用してサイトでグローバル・アクション・ハンドラーを設定するための
標準メカニズムを使用して、このグローバル・アクション用のハンドラーを提供することができます。
この属性が true である場合は、class 属性は提供されません。
-
allowLabelUpdates - retarget が true である場合にのみ適用されます。
この属性が true の場合は、retarget アクションによって、そのハンドラーからラベルとツールのヒントが
更新されます。
-
enablesFor - アクションを使用可能にするために満たす必要のある選択カウントを示す値。
この属性が指定され、条件が満たされると、アクションが使用可能になります。
条件が満たされない場合、アクションは使用不可になります。
属性が指定されない場合、アクションは選択された項目の数にかかわらず使用可能となります。
次の属性形式がサポートされます。
! - 選択された項目が 0
? - 選択された項目が 0 または 1
+ - 選択された項目が 1 つ以上
multiple, 2+ - 選択された項目が 2 つ以上
n - 選択された項目の数 (たとえば 4)。
* - 任意数の項目を選択
<!ELEMENT selection EMPTY>
<!ATTLIST selection
class
CDATA #REQUIRED
name
CDATA #IMPLIED
>
-
class - アクションを使用可能にするため、選択内の各オブジェクトがサブクラス化または
インプリメントするクラスまたはインターフェースの完全修飾名。
-
name - 選択内のオブジェクトにオプションで適用可能な名前のワイルドカード・フィルター。
このフィルターを指定して、マッチングに失敗すると、アクションは使用不可になります。
<!ELEMENT enablement (and | or | not | objectClass
| objectState | systemProperty | pluginState)*>
<!ATTLIST enablement EMPTY>
Eclipse のバージョン 2.0 では、enablement エレメントは、アクションの使用可能性を
定義するために使用されます。
enablement エレメントの詳細については、actionExpressions.html を
参照してください。
例:
アクション・セットの例を次に示します (サブエレメントと way 属性が使用されています)。
<extension point = "org.eclipse.ui.actionSets">
<actionSet id="com.xyz.actionSet"
label="My Actions"
visible="true">
<menu id="com.xyz.xyzMenu"
label="XYZ Menu"
path="additions">
<separator name="group1"/>
</menu>
<action id="com.xyz.runXYZ"
label="&Run XYZ Tool"
menubarPath="com.xyz.xyzMenu/group1"
toolbarPath="Normal/XYZ"
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="&Run ABC Tool"
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">
</action>
</actionSet>
</extension>
上の例では、指定されたアクション "My Actions" は、各パースペクティブ中、初期状態で可視と
なります。
これは、単一選択 (enablesFor 属性) に対してのみ使用可能となります。
また、選択内のオブジェクトは、指定されたインターフェース (IFile) をインプリメントする
必要があり、Java ファイルである必要があります。
API 情報: class 属性の値は、
org.eclipse.ui.IWorkbenchWindowActionDelegate または
org.eclipse.ui.IWorkbenchWindowPulldownDelegate をインプリメントするクラスの完全修飾名で
ある必要があります。
後者は、pulldown が true の場合にインプリメントする必要があります。
このクラスは、プラグイン全体が必要になる前に全体がロードされることのないよう、
できる限り後からロードされます。
アクション拡張の使用可能性の基準は、最初は enablesFor, selection および
enablement によって定義されています。
ただし、アクション代行がインスタンス化されると、その selectionChanged メソッド内の
アクション使用可能状態を直接制御できます。
ワークベンチはプラグインの代わりにメニューを生成しないことに注意してください。
メニュー・パスは、既存の参照メニューでなければなりません。
アクションおよびメニュー・ラベルには、次の規則に従い、簡略記号とアクセラレーターをエンコードする
特殊文字を含むことができます。
-
略号は、変換されたテキスト中の選択文字の前のアンパーサンド ('&') 文字で指定されます。
XML ストリングではアンパーサンドは使用できないため、& 文字エンティティーを
使用してください。
-
オプションのアクセラレーターは、名前ストリングの最後で指定します。
ここには、@ に続けて一連の修飾子と最終的なアクセラレーター文字を続けます (たとえば &Save@Ctrl+S)。
修飾子は、'+' 符号を区切り文字としてつなげることができます (@Ctrl+Shift+S など)。
複数のアクションがメニューまたはツールバーに 1 つの拡張によって与えられる場合、
アクションは plugin.xml ファイルとは逆の順序でリストされます。
この振る舞いは、通常は一目ではわかりません。
ただし、これは Eclipse Platform API がフリーズした後で発見されます。
振る舞いを変更すると、既存の振る舞いに依存する各プラグインが中断する可能性があります。
提供されるインプリメンテーション:
プラグインはこの拡張ポイントを使用して新規のトップレベル・メニューを追加することができます
(例、Debug)。
また、プラグインは、
他のプラグインのアクションが提供されるようにするための名前付きグループを定義することもできます。
トップレベル・メニューは、path 属性に次の値を使用して作成されます。
-
additions -「ウィンドウ」メニューの左側にあるグループを表します。
path 属性を省略すると、additions メニュー・バー・グループに新規のメニューが
追加されます。
ワークベンチ・ウィンドウのデフォルト・グループは IWorkbenchActionConstants インターフェースで
定義されます。
これらの定数は、動的な contribution のコードで使用することができます。
この値は、XML ファイルにコピーして、既存のワークベンチ・メニューおよびツールバーとの詳細な統合を
図ることができます。
ワークベンチ・ウィンドウ内の各種メニューおよびツールバー項目は、アルゴリズムに従って定義されます。
この場合、ウィンドウの拡張には個別のメカニズムが使用されます。
たとえば、新規のワークベンチ・ビューを追加することによって、「パースペクティブ」メニューには新しいメニュー項目が表示されます。
インポート、エクスポート、および新規ウィザードの拡張機能も自動的にウィンドウに追加されます。