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

org.eclipse.ui.viewActions

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

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

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

<!ELEMENT extension (viewContribution+)>

<!ATTLIST extension

point CDATA #REQUIRED

id    CDATA #IMPLIED

name  CDATA #IMPLIED>


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

<!ATTLIST viewContribution

id       CDATA #REQUIRED

targetID CDATA #REQUIRED>

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



<!ELEMENT action (selection* | enablement?)>

<!ATTLIST action

id            CDATA #REQUIRED

label         CDATA #REQUIRED

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>

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



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

>

<viewContribution id=

"com.xyz.xyzViewC1"

targetID=

"org.eclipse.ui.views.navigator.ResourceNavigator"

>

<menu id=

"com.xyz.xyzMenu"

label=

"Меню XYZ"

path=

"additions"

>

<separator name=

"group1"

/>

</menu>

<action id=

"com.xyz.runXYZ"

label=

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

menubarPath=

"com.xyz.xyzMenu/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>

</viewContribution>

</extension>

В приведенном выше примере указанное действие будет подключаться только при выборе одного объекта (атрибут enablesFor). Кроме того, выбранный объект должен быть файлом Java.

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

   

<extension point=

"org.eclipse.ui.viewActions"

>

<viewContribution id=

"com.xyz.xyzViewC1"

targetID=

"org.eclipse.ui.views.navigator.ResourceNavigator"

>

<menu id=

"com.xyz.xyzMenu"

label=

"Меню XYZ"

path=

"additions"

>

<separator name=

"group1"

/>

</menu>

<action id=

"com.xyz.runXYZ2"

label=

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

menubarPath=

"com.xyz.xyzMenu/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>

</viewContribution>

</extension>

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

Значение атрибута class должно быть полным именем класса Java, реализующего интерфейс org.eclipse.ui.IViewActionDelegate. Этот класс необходимо загружать как можно позже, чтобы избежать загрузки всего модуля, до того как он потребуется в действительности.

Интерфейс org.eclipse.ui.IViewActionDelegate расширяет интерфейс org.eclipse.ui.IActionDelegate и добавляет дополнительный метод, который позволяет инициализировать делегат с экземпляром панели, в которую он добавляется.

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

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

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