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

org.eclipse.ui.actionSets

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

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

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

Синтаксис элементов enablement и visibility одинаков. Оба содержат только один подэлемент булевского выражения. В простейшем случае это будет элемент objectClass, objectState, pluginState или systemProperty. В более сложном случае для создания булевского выражения можно использовать сочетания элементов and, or и not. Элементы and и or должны содержать по 2 подэлемента. Элемент 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>

Этот элемент определяет действие, которое может вызываться пользователем в интерфейсе.



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

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



<!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 (соответствует "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>

С помощью этой точки расширения модули могут добавлять новые меню верхнего уровня. Кроме того, модули могут определять группы с именами, в которые смогут добавлять свои действия другие модули.

Меню верхнего уровня создаются с помощью следующих значений атрибута пути:

Отсутствие атрибута пути приведет к добавлению нового меню в группу additions главного меню.

Группы по умолчанию в окне рабочей среды определяются в интерфейсе IWorkbenchActionConstants. Эти константы можно использовать в коде для динамического добавления. Значения можно также скопировать в файл XML для более сложной интеграции с существующими меню и панелью инструментов рабочей среды.

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