Наборы действий

org.eclipse.ui.actionSets

Эта точка расширения служит для добавления меню, пунктов меню и кнопок панели инструментов в общие области окна Рабочая среда. Эти добавления объединяются под общим названием набор действий и показаны в окне Рабочая среда пользователю, настраивающему проекцию.

Включение и/или область видимости действия определяются с помощью элементов enablement и visibility соответственно. В обоих этих элементах содержится вычисляемое булевское выражение.

Синтаксис элементов enablement и visibility одинаков. Оба содержат только один субэлемент - булевское выражение. В простейшем случае это элемент objectClass, objectState, pluginState или systemProperty. В более сложном случае в булевское выражение могут быть добавлены элементы and, or и not. У элементов and и or должно быть по два субэлемента. У элемента not - один субэлемент.

<!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)>

Это - булевская операция AND над результатами вычисления двух операндов выражения.



<!ELEMENT or (and | or | not | objectClass | objectState | pluginState | systemProperty)>

Это - булевская операция OR над результатами вычисления двух операндов выражения.



<!ELEMENT not (and | or | not | objectClass | objectState | pluginState | systemProperty)>

Это - булевская операция NOT над результатами вычисления двух операндов выражения.



<!ELEMENT objectClass EMPTY>

<!ATTLIST objectClass

name CDATA #REQUIRED>

Этот элемент служит для проверки класса или интерфейса каждого объекта в текущем выборе. Если каждый выбранный объект реализует заданный класс или интерфейс, то результатом выражения будет true.



<!ELEMENT objectState EMPTY>

<!ATTLIST objectState

name  CDATA #REQUIRED

value CDATA #REQUIRED>

Этот элемент служит для проверки состояния атрибута каждого объекта в текущем выборе. Если у каждого выбранного объекта атрибут находится в заданном состоянии, то результатом выражения будет true. Для вычисления выражения этого типа каждый выбранный объект должен реализовывать интерфейс org.eclipse.ui.IActionFilter или преобразовывать к нему.



<!ELEMENT pluginState EMPTY>

<!ATTLIST pluginState

id    CDATA #REQUIRED

value (installed|activated) "installed">

Этот элемент применяется для выяснения состояния модуля. Состояние модуля может принимать значения: installed (соответствует "resolved" в OSGi) или activated (соответствует "active" в OSGi).



<!ELEMENT systemProperty EMPTY>

<!ATTLIST systemProperty

name  CDATA #REQUIRED

value CDATA #REQUIRED>

Этот элемент применяется для выяснения состояния некоторого системного свойства. Значение свойства извлекается из java.lang.System.



Ниже приведен пример набора действий (заметьте, что используются субэлементы и атрибуты пути):

    

<extension point =

"org.eclipse.ui.actionSets"

>

<actionSet id=

"com.xyz.actionSet"

label=

"Действия"

>

<menu id=

"com.xyz.xyzMenu"

label=

"Меню XYZ"

path=

"additions"

>

<separator name=

"group1"

/>

<separator name=

"option1"

/>

</menu>

<action id=

"com.xyz.runXYZ"

label=

"&amp;Запустить инструмент XYZ"

style=

"toggle"

state=

"false"

menubarPath=

"com.xyz.xyzMenu/group1"

icon=

"icons/runXYZ.gif"

tooltip=

"Запустить инструмент XYZ"

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;Запустить инструмент ABC"

style=

"push"

menubarPath=

"com.xyz.xyzMenu/group1"

toolbarPath=

"Normal/XYZ"

icon=

"icons/runABC.gif"

tooltip=

"Запустить инструмент ABC"

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;Запустить инструмент DEF"

style=

"radio"

state=

"true"

menubarPath=

"com.xyz.xyzMenu/option1"

icon=

"icons/runDEF.gif"

tooltip=

"Запустить инструмент DEF"

class=

"com.xyz.actions.RunDEF"

helpContextId=

"com.xyz.run_def_action_context"

>

</action>

<action id=

"com.xyz.runGHI"

label=

"&amp;Запустить инструмент GHI"

style=

"radio"

state=

"false"

menubarPath=

"com.xyz.xyzMenu/option1"

icon=

"icons/runGHI.gif"

tooltip=

"Запустить инструмент GHI"

class=

"com.xyz.actions.RunGHI"

helpContextId=

"com.xyz.run_ghi_action_context"

>

</action>

<action id=

"com.xyz.runJKL"

label=

"&amp;Запустить инструмент JKL"

style=

"radio"

state=

"false"

menubarPath=

"com.xyz.xyzMenu/option1"

icon=

"icons/runJKL.gif"

tooltip=

"Запустить инструмент JKL"

class=

"com.xyz.actions.RunJKL"

helpContextId=

"com.xyz.run_jkl_action_context"

>

</action>

</actionSet>

</extension>

В приведенном выше примере указанный набор действий, названный "Действия", первоначально невидим во всех проекциях, потому что атрибут 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;.
При добавлении двух или более действий в меню или панель инструментов посредством одного расширения эти действия будут показаны в обратном порядке по сравнению с тем, в котором они указаны в файле plugin.xml. Это неожиданный факт. Однако он был обнаружен уже после выпуска API платформы Eclipse. Исправление ситуации нарушит работу всех модулей, в которых выполняется эта операция.

Элементы selection и enablement взаимоисключающи. Элемент enablement может заменить элемент selection с помощью субэлементов objectClass и objectState. Например, фрагмент:

 

<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. Эти константы можно использовать в коде для динамического добавления. Значения можно также скопировать в файл XML для более сложной интеграции с существующими меню и панелью инструментов рабочей среды.

Различные пункты меню и панели инструментов в окне рабочей среды определяются алгоритмически. В этих случаях расширение окна следует выполнять с помощью отдельного механизма. Например, при добавлении новой панели рабочей среды в меню Проекция появляется новый пункт меню. Расширения - мастеры импорта, экспорта и создания также добавляются в окно автоматически.