При неоднородном выборе добавляемое действие будет применяться в том случае, если оно зарегистрировано для общего типа выбора (если он возможен). Если точное совпадение невозможно, будет сделана попытка применить действия, указанные для базовых классов и интерфейсов.
Для дополнительного ограничения выбора можно использовать фильтр имен. При использовании фильтра дополнение будет применяться только в том случае, если все выбранные объекты будут удовлетворять условию фильтрации.
Атрибут 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>
Этот элемент определяет действие, которое может вызываться пользователем в интерфейсе.
push | - элемент обычного меню или панели инструментов. | |
radio | - элемент меню или панели инструментов в виде переключателя - радиокнопки. Внутри группы действий, оформленных в таком стиле, возможен выбор только одного действия (аналогично переключению кнопок старого проводного радио). Начальное значение определяется атрибутом state. | |
toggle | - переключатель в виде флажка (в меню) или переключатель в панели инструментов. Начальное значение определяется атрибутом state. | |
pulldown | - элемент каскадного меню. |
! | - выбрано 0 элементов | |
? | - выбран 1 элемент или не выбрано ни одного | |
+ | - выбран 1 или более элементов | |
multiple, 2+ | - выбрано 2 или более элементов | |
n | - точное число выбранных элементов. Например: enablesFor=" 4" подключает действие, только если выбрано 4 элемента | |
* | - выбрано любое число элементов |
Критерий подключения для расширения действия первоначально определяется элементами enablesFor, selection и enablement. Однако как только создан экземпляр делегата действия, он может управлять состоянием подключения действия непосредственно внутри его метода selectionChanged.
<!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.
В приведенном выше примере действие, добавляемое для объекта, подключается только при выборе одного объекта (атрибут enablesFor). Кроме того, каждый выбранный объект должен реализовать указанный интерфейс (IFile) и быть файлом Java. Это действие будет добавлено в предварительно созданное субменю. Это дополнение будет применяться в любой панели с указанным типом выбора.<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=
"&XYZ Java Tools"
>
<separator name=
"group1"
/>
</menu>
<action id=
"com.xyz.runXYZ"
label=
"&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=
"&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>
Дополнение к средству отображения, наоборот, появится только в контекстном меню панели Задачи, и не будет зависеть от типа выбора.
Ниже приведен пример механизма фильтрации. В этом случае действие будет доступно только для завершенных интерфейсов IMarker с высоким приоритетом.
Ниже приведен пример использования элемента visibility:<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>
<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=
"&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.
Примечание: Для обратной совместимости для добавлений объектов может быть реализован интерфейс org.eclipse.ui.IActionDelegate.
Расширение контекстного меню внутри компонентов панели или редактора возможно только в том случае, если целевой компонент публикует меню для расширения. Настоятельно рекомендуем делать это для улучшения расширяемости продукта. Для этого каждый компонент должен опубликовать все контекстные меню, которые определены, с помощью метода IWorkbenchPartSite.registerContextMenu. Как только это будет сделано, рабочая среда автоматически вставит все существующие расширения действий.
Для каждого зарегистрированного меню необходимо задать идентификатор. Для совместимости компонентов все средства их реализации должны придерживаться следующей стратегии.
Любое контекстное меню, зарегистрированное с рабочей средой, должно также содержать стандартную точку вставки с идентификатором IWorkbenchActionConstants.MB_ADDITIONS. Это значение будет использоваться другими модулями как контрольная точка для вставки. Для определения точки вставки можно добавить GroupMarker в то место в меню, где должна производиться вставка.
Объект в рабочей области, представляющий собой выбор в контекстном меню, может определять интерфейс org.eclipse.ui.IActionFilter. Фильтрация по типу может выполняться стратегией фильтрации. При извлечении фильтра для выбора рабочая среда будет проверять, реализует ли он интерфейс IActionFilter. Если нет, то рабочая среда будет запрашивать фильтр через интерфейс IAdaptable.
Метки действий и меню могут включать специальные символы для представления мнемонической информации. Для определения такого символа в локализованном тексте перед ним вставляется амперсанд ('&'). Поскольку строки XML не могут содержать амперсанд, следует использовать элемент &.
Если в меню добавляются два и более действий с помощью одного расширения, то действия появляются в обратном порядке по отношению к их последовательности в файле 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>
Copyright (c) 2000, 2005 IBM Corporation и другие.
Все права защищены. Эта программа и сопутствующие материалы распространяются на условиях Eclipse Public License v1.0, поставляемой вместе с продуктом и доступной на Web-сайте
http://www.eclipse.org/legal/epl-v10.html