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

org.eclipse.ui.editorActions

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

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

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

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

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

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



<!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.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;Запуск инструмента XYZ"

menubarPath=

"XYZ/group1"

toolbarPath=

"Normal/additions"

style=

"toggle"

state=

"true"

icon=

"icons/runXYZ.gif"

tooltip=

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

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

menubarPath=

"edit/XYZ2/group1"

style=

"push"

icon=

"icons/runXYZ2.gif"

tooltip=

"Запуск инструмента XYZ2"

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>

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