Меню, панели инструментов и действия редакторов

org.eclipse.ui.editorActions

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

Начальный комплект дополнений для редактора определяется с помощью другой точки расширения (org.eclipse.ui.editors). Создается один общий комплект для всех экземпляров редакторов одного типа. Действия выполняются в активном редакторе. Эта точка расширения следует тому же принципу. Создается одно общее расширение действия для всех экземпляров редакторов одного типа. Для реализации org.eclipse.ui.IEditorActionDelegate необходим класс действия. Активный редактор передается делегату путем вызова IEditorActionDelegate.setActiveEditor.

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

Синтаксис элементов enablement и visibility одинаков. В оба эти элемента входит только один дочерний элемент - булевское выражение. В простейшем случае это будет элемент objectClass, objectState, pluginState или systemProperty. В более сложных - булевское выражение формируется с помощью элементов И, ИЛИ и НЕ. В элементах И и ИЛИ должно быть по два дочерних элемента. В элементе НЕ - только один.

<!ELEMENT extension (editorContribution+)>

<!ATTLIST extension

point CDATA #REQUIRED

id    CDATA #IMPLIED

name  CDATA #IMPLIED>


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

<!ATTLIST editorContribution

id       CDATA #REQUIRED

targetID CDATA #REQUIRED>

Этот элемент определяет группу действий и/или меню редактора.



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

state         (true | false)

class         CDATA #REQUIRED

enablesFor    CDATA #IMPLIED

actionID      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, то selection игнорируется.



<!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.editorActions"

>

<editorContribution id=

"com.xyz.xyzContribution"

targetID=

"com.ibm.XMLEditor"

>

<menu id=

"XYZ"

label=

"&amp;XYZ Menu"

>

<separator name=

"group1"

/>

</menu>

<action id=

"com.xyz.runXYZ"

label=

"&amp;Run XYZ Tool"

menubarPath=

"XYZ/group1"

toolbarPath=

"Normal/additions"

style=

"toggle"

state=

"true"

icon=

"icons/runXYZ.gif"

tooltip=

"Run XYZ Tool"

helpContextId=

"com.xyz.run_action_context"

class=

"com.xyz.actions.RunXYZ"

>

<selection class=

"org.eclipse.core.resources.IFile"

name=

"*.java"

/>

</action>

</editorContribution>

</extension>

В этом примере заданное действие появится в виде переключателя в новом меню верхнего уровня с именем "XYZ Menu", и в виде кнопки-переключателя в панели инструментов. Действие будет разрешено, если выбраны только файлы Java.

Другой пример расширения действия редактора:

   

<extension point=

"org.eclipse.ui.editorActions"

>

<editorContribution id=

"com.xyz.xyz2Contribution"

targetID=

"com.ibm.XMLEditor"

>

<menu id=

"XYZ2"

label=

"&amp;XYZ2 Menu"

path=

"edit/additions"

>

<separator name=

"group1"

/>

</menu>

<action id=

"com.xyz.runXYZ2"

label=

"&amp;Run XYZ2 Tool"

menubarPath=

"edit/XYZ2/group1"

style=

"push"

icon=

"icons/runXYZ2.gif"

tooltip=

"Run XYZ2 Tool"

helpContextId=

"com.xyz.run_action_context2"

class=

"com.xyz.actions.RunXYZ2"

>

<enablement>

<and>

<objectClass name=

"org.eclipse.core.resources.IFile"

/>

<not>

<objectState name=

"extension"

value=

"java"

/>

</not>

</and>

</enablement>

</action>

</editorContribution>

</extension>

В этом примере заданное действие появится в подменю "XYZ2 Menu" меню "Edit" в виде пункта меню. Действие будет разрешено, если не выбран ни один файл Java.

Значение атрибута класса должно быть полным именем класса Java, реализующего org.eclipse.ui.IEditorActionDelegate. Этот класс следует загружать как можно позднее, чтобы предотвратить преждевременную загрузку всего модуля. Всякий раз при активации редактора заданного типа будет вызываться метод setActiveEditor. Для всех экземпляров заданного типа редактора будет создан только один набор действий и меню, независимо от количества экземпляров редактора, открытых в рабочей среде.

Эта точка расширения может служить для добавления действий в меню, предварительно созданные целевым редактором. Кроме того, меню и действия можно добавить в окно рабочей среды. Идентификаторы действий и главных групп в окне рабочей среды определяются в org.eclipse.ui.IWorkbenchActionConstants. Это базовая точка для добавления новых действий. Меню верхнего уровня создаются с помощью следующих значений атрибута пути:

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

Действия и меню, добавляемые в эти пути, будут показываться только тогда, когда активен связанный редактор. После закрытия редактора действия и меню удаляются.

Первоначально критерий разрешения для расширения действия определяется с помощью 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>

В рабочую среду встроен редактор "Стандартный текстовый редактор". Модули можно добавлять как в этот редактор, так и в редакторы, поставляемые другими модулями.