Всплывающие меню

org.eclipse.ui.popupMenus

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

При неоднородном выборе добавляемое действие будет применяться в том случае, если оно зарегистрировано для общего типа выбора (если он возможен). Если точное совпадение невозможно, будет сделана попытка применить действия, указанные для базовых классов и интерфейсов.

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

Атрибут enablesFor, задаваемый для отдельных добавляемых действий, позволяет указать, для какого типа выбора применяется действие: одного объекта, нескольких объектов или для какого-то другого типу выбора.

Если указанных способов фильтрации недостаточно, для добавления действия можно использовать элемент filter. В этом случае атрибуты целевого объекта описываются набором пар имен-значений. Атрибуты, применяемые к выбранным объектам, зависят от типа и находятся вне домена самой рабочей среды, поэтому для фактического выбора рабочая среда делегирует фильтрацию на этот уровень.

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

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

<!ELEMENT extension (objectContribution , viewerContribution)>

<!ATTLIST extension

point CDATA #REQUIRED

id    CDATA #IMPLIED

name  CDATA #IMPLIED>


<!ELEMENT objectContribution (filter* , visibility? , enablement? , menu* , action*)>

<!ATTLIST objectContribution

id          CDATA #REQUIRED

objectClass CDATA #REQUIRED

nameFilter  CDATA #IMPLIED

adaptable   (true | false) "false">

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



<!ELEMENT viewerContribution (visibility? , menu* , action*)>

<!ATTLIST viewerContribution

id       CDATA #REQUIRED

targetID CDATA #REQUIRED>

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



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

<!ATTLIST action

id               CDATA #REQUIRED

label            CDATA #REQUIRED

definitionId     CDATA #IMPLIED

menubarPath      CDATA #IMPLIED

icon             CDATA #IMPLIED

helpContextId    CDATA #IMPLIED

style            (push|radio|toggle|pulldown)

state            (true | false)

class            CDATA #REQUIRED

enablesFor       CDATA #IMPLIED

overrideActionId CDATA #IMPLIED

tooltip          CDATA #IMPLIED>

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



<!ELEMENT filter EMPTY>

<!ATTLIST filter

name  CDATA #REQUIRED

value CDATA #REQUIRED>

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



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

>

<objectContribution id=

"com.xyz.C1"

objectClass=

"org.eclipse.core.resources.IFile"

nameFilter=

"*.java"

>

<menu id=

"com.xyz.xyzMenu"

path=

"additions"

label=

"&amp;XYZ Java Tools"

>

<separator name=

"group1"

/>

</menu>

<action id=

"com.xyz.runXYZ"

label=

"&amp;Run XYZ Tool"

style=

"push"

menubarPath=

"com.xyz.xyzMenu/group1"

icon=

"icons/runXYZ.gif"

helpContextId=

"com.xyz.run_action_context"

class=

"com.xyz.actions.XYZToolActionDelegate"

enablesFor=

"1"

/>

</objectContribution>

<viewerContribution id=

"com.xyz.C2"

targetID=

"org.eclipse.ui.views.TaskList"

>

<action id=

"com.xyz.showXYZ"

label=

"&amp;Show XYZ"

style=

"toggle"

state=

"true"

menubarPath=

"additions"

icon=

"icons/showXYZ.gif"

helpContextId=

"com.xyz.show_action_context"

class=

"com.xyz.actions.XYZShowActionDelegate"

/>

</viewerContribution>

</extension>

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

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

Ниже приведен пример механизма фильтрации. В этом случае действие будет доступно только для завершенных интерфейсов IMarker с высоким приоритетом.

   

<extension point=

"org.eclipse.ui.popupMenus"

>

<objectContribution id=

"com.xyz.C3"

objectClass=

"org.eclipse.core.resources.IMarker"

>

<filter name=

"done"

value=

"true"

/>

<filter name=

"priority"

value=

"2"

/>

<action id=

"com.xyz.runXYZ"

label=

"High Priority Completed Action Tool"

icon=

"icons/runXYZ.gif"

class=

"com.xyz.actions.MarkerActionDelegate"

>

</action>

</objectContribution>

</extension>

Ниже приведен пример использования элемента visibility:

   

<extension point=

"org.eclipse.ui.popupMenus"

>

<viewerContribution id=

"com.xyz.C4"

targetID=

"org.eclipse.ui.views.TaskList"

>

<visibility>

<and>

<pluginState id=

"com.xyz"

value=

"activated"

/>

<systemProperty name=

"ADVANCED_MODE"

value=

"true"

/>

</and>

</visibility>

<action id=

"com.xyz.showXYZ"

label=

"&amp;Show XYZ"

style=

"push"

menubarPath=

"additions"

icon=

"icons/showXYZ.gif"

helpContextId=

"com.xyz.show_action_context"

class=

"com.xyz.actions.XYZShowActionDelegate"

>

</action>

</viewerContribution>

</extension>

В приведенном выше примере указанное действие появляется как пункт контекстного меню панели Задачи, но только в том случае, если модуль "com.xyz" активен, а для указанного системного свойства установлено значение true.

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

Примечание: Для обратной совместимости для добавлений объектов может быть реализован интерфейс org.eclipse.ui.IActionDelegate.

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

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

Любое контекстное меню, зарегистрированное с рабочей средой, должно также содержать стандартную точку вставки с идентификатором IWorkbenchActionConstants.MB_ADDITIONS. Это значение будет использоваться другими модулями как контрольная точка для вставки. Для определения точки вставки можно добавить GroupMarker в то место в меню, где должна производиться вставка.

Объект в рабочей области, представляющий собой выбор в контекстном меню, может определять интерфейс org.eclipse.ui.IActionFilter. Фильтрация по типу может выполняться стратегией фильтрации. При извлечении фильтра для выбора рабочая среда будет проверять, реализует ли он интерфейс IActionFilter. Если нет, то рабочая среда будет запрашивать фильтр через интерфейс IAdaptable.

Метки действий и меню могут включать специальные символы для представления мнемонической информации. Для определения такого символа в локализованном тексте перед ним вставляется амперсанд ('&'). Поскольку строки 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>

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