С помощью этой точки расширения разработчик модуля может определять меню, разделители, логические группы и элементы меню -- в любом месте приложения, от строк состояния до контекстных меню. Можно также определить наборы таких дополнений (то есть, наборов действий); конечный пользователь может включать и выключать эти наборы действий. В общих чертах, точка расширения меню содержит все элементы представления (за исключением значков) для внесения в любое меню или ограниченную область в Eclipse.
Каждый элемент в данной точке расширения имеет уникальный идентификатор. Это необходимо для того, чтобы на эти элементы можно было ссылаться в любом месте без необходимости сброса состояния элемента. Например, идентификатор может потребоваться при упорядочении или при определении набора действий. Также это позволяет разработчикам модулей из других фирм размещать эти элементы в требуемых расположениях в интерфейсе.
Примечание: Для версии 3.2 единственной реализованной частью этого механизма расширений является часть, связанная с дополнениями 'trim'. Попытка добавить элементы, меню, панели инструментов или записи строк состояния будет действовать как пустая операция.
<!ELEMENT extension (item* , menu* , group* , widget*)>
<!ATTLIST extension
point CDATA #REQUIRED
id CDATA #IMPLIED
name CDATA #IMPLIED>
<!ELEMENT item (parameter* , location* , visibleWhen?)>
<!ATTLIST item
id CDATA #REQUIRED
commandId CDATA #REQUIRED
menuId CDATA #IMPLIED>
Элемент может являться элементом меню или элементом trim, в зависимости от размещения. Связанные с этим элементом текст и изображение будут извлечены из команды.
org.eclipse.ui
, может называться org.eclipse.ui.item1
.<!ELEMENT menu (location* , visibleWhen?)>
<!ATTLIST menu
id CDATA #REQUIRED
label CDATA #IMPLIED>
Меню может быть либо прикреплено к элементу инструмента, либо появиться где-либо в меню панели, контекстном меню или строке меню верхнего уровня. Разработчик модуля может считать, что существует меню и панель инструментов для каждой панели, и что существует строка меню верхнего уровня. Контекстные меню перед применением необходимо зарегистрировать программным образом (см. информацию по API).
Меню может содержать только группы.
org.eclipse.ui
, может называться org.eclipse.ui.menu1
.<!ATTLIST group
id CDATA #REQUIRED
separatorsVisible (true | false) "true">
Логическая группа. Может быть видимой (то есть, до и после нее помещаются разделители) и невидимой. По умолчанию логические группы являются видимыми.
Группа может содержать меню, элементы и другие группы.
org.eclipse.ui
, может называться org.eclipse.ui.group1
.<!ELEMENT widget (location* , class? , visibleWhen? , layout?)>
<!ATTLIST widget
id CDATA #REQUIRED
class CDATA #REQUIRED>
Элементы меню или врезки с прямым доступом к виджетам. Их можно использовать, например, для поля со списком. К сожалению, это означает, что если элемент виджета становится видимым в пользовательском интерфейсе, то это приводит к загрузке модуля. Следует использовать этот элемент с осторожностью, поскольку он может привести к снижению производительности. Это также вызывает неполадки, например, при поддержке макросов, написании сценариев и при использовании других основанных на командах механизмов. Отображение виджета врезки в пользовательском интерфейсе приведет к загрузке модуля.
org.eclipse.ui
, может называться org.eclipse.ui.widget1
.IWorkbenchWidget
. Клиенты могут использовать реализацию по умолчанию; AbstractWorkbenchTrimWidget
.
Эта реализация управляет методом 'init' и кэширует результат для использования с помощью метода getWorkbenchWindow
. <!ELEMENT layout EMPTY>
<!ATTLIST layout
fillMajor (true | false)
fillMinor (true | false) >
Этот элемент можно использовать для указания различных опций размещения для элементов, добавленных в расположения trim
.
false
.false
.<!ELEMENT location (order? , (bar | part | popup))>
<!ATTLIST location
mnemonic CDATA #IMPLIED
imageStyle CDATA #IMPLIED>
Расположение, в котором может появиться menu
, group
, item
или widget
.
Этот элемент применяется для управления информацией, связанной с данным расположением.
<!ELEMENT bar EMPTY>
<!ATTLIST bar
type (menu|trim)
path CDATA #IMPLIED>
Концевой элемент в расположении. Это может быть строка меню или область врезки. Если не уточнено, то этот элемент указывает на
строку меню или врезку верхнего уровня. Если элемент квалифицирован как элемент part
, то он указывает на меню
или врезку этого компонента.
menu
или trim
.
При внесении дополнения в меню элемент будет встроен в структуру виджета. В общем, это означает, что использование элементов
виджета не имеет особого смысла, и значок для команды элемента не является необходимым. Значение по умолчанию - menu
.
При внесении дополнения ко врезке (trim
) на панель вместо отдельной команды или значка нужно добавить виджет, в котором
будет показана информация врезки.
Во врезке рабочая среда определяет пять основных групп, которые соответствуют различным расположениям в окне:
vertical1
.'/'
. <!ATTLIST class
class CDATA #REQUIRED>
Элемент класса, поддерживающий исполняемый синтаксис расширения для элементов widget
и dynamic
.
IExecutableExtension
.<!ELEMENT visibleWhen (not | or | and | instanceof | test | systemTest | equals | count | with | resolve | adapt | iterate)>
<!ATTLIST visibleWhen
checkEnabled (true | false) "false">
Управляет областью видимости данного элемента.
true
, то вложенные элементы не разрешены.
Этот атрибут проверяет состояние команды, и если команда включена, делает соответствующий элемент видимым.<!ATTLIST part
id CDATA #IMPLIED
class CDATA #IMPLIED>
Элемент в расположении. Квалифицирует расположение для обращения в определенному компоненту рабочей среды. Это может быть либо панель, либо редактор. В квалификации может применяться либо имя класса пути (включая наследование), либо ссылка на идентификатор панели или редактора.
Можно указать либо id
, либо class
(но не оба).
<!ELEMENT parameter EMPTY>
<!ATTLIST parameter
name CDATA #REQUIRED
value CDATA #REQUIRED>
Параметр либо исполняемого расширения, либо команды -- в зависимости от его расположения в расширении.
<!ELEMENT order EMPTY>
<!ATTLIST order
position (start|end|before|after)
relativeTo CDATA #IMPLIED>
Управляет положением меню, группы, элемента или виджета в определенном расположении.
Этот атрибут может иметь следующие значения: start
(поместить элемент в начале контейнера); end
(поместить
элемент в конце контейнера); after
(поместить элемент после сестринского элемента, ИД которого соответствует ref
);
и before
(поместить элемент перед сестринским элементом, ИД которого соответствует ref
). К любому типу
элементов меню можно применить относительное упорядочение.
В случае возникновения конфликта Eclipse выберет произвольный порядок. Единственной гарантией сохранения прежнего порядка в случае возникновения конфликта является выполнение следующих условий:
position
равно before
или after
.<!ELEMENT popup EMPTY>
<!ATTLIST popup
id CDATA #IMPLIED
path CDATA #IMPLIED>
Компонент расположения. Указывает, что меню, группа, элемент или виджет должны появляться во всплывающем меню.
<!ELEMENT enablement (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>
Шаблонный корневой элемент. Этот элемент может использоваться внутри точки расширения для определения ее выражения enablement. Для объединения подэлементов выражения enablement используется операция and.
<!ELEMENT not (not | and | or | instanceof | test | systemTest | equals | count | with | resolve | adapt | iterate)>
Этот элемент представляет операцию НЕ над результатом вычисления выражения его подэлемента.
<!ELEMENT and (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>
Этот элемент представляет операцию И над результатом вычисления выражений всех его подэлементов.
<!ELEMENT or (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>
Этот элемент представляет операцию ИЛИ над результатом вычисления выражений всех его подэлементов.
<!ELEMENT instanceof EMPTY>
<!ATTLIST instanceof
value CDATA #REQUIRED>
Этот элемент позволяет проверить допустимость преобразования типа выбранного объекта к указанному типу. Выражение возвращает EvaluationResult.TRUE, если тип объекта является производным типом типа, указанного в значении атрибута. В противном случае возвращается EvaluationResult.FALSE.
<!ELEMENT test EMPTY>
<!ATTLIST test
property CDATA #REQUIRED
args CDATA #IMPLIED
value CDATA #IMPLIED>
Этот элемент используется для проверки состояния свойства выбранного объекта. Набор тестируемых свойств можно расширить с помощью точки расширения средства тестирования свойств. Выражение test возвращает EvaluationResult.NOT_LOADED, если средство тестирования свойств, выполняющее фактическую проверку, еще не загружено.
<!ELEMENT systemTest EMPTY>
<!ATTLIST systemTest
property CDATA #REQUIRED
value CDATA #REQUIRED>
Тестирует системное свойство, вызывая для этого метод System.getProperty и сравнивая результат со значением, указанным в атрибуте value.
<!ELEMENT equals EMPTY>
<!ATTLIST equals
value CDATA #REQUIRED>
Этот элемент применяется для выполнения проверки equals объекта в фокусе. Выражение возвращает EvaluationResult.TRUE, если объект равен значению атрибута value. В противном случае возвращается EvaluationResult.FALSE.
<!ELEMENT count EMPTY>
<!ATTLIST count
value CDATA #REQUIRED>
Этот элемент применяется для проверки числа элементов в наборе.
<!ELEMENT with (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>
<!ATTLIST with
variable CDATA #REQUIRED>
Этот элемент изменяет проверяемый объект для всех своих подэлементов, заменяя его объектом, на который указывает переменная в атрибуте variable. Если разрешить переменную невозможно, то при вычислении выражения возбуждается ситуация ExpressionException. Для объединения подэлементов выражения with используется операция and.
<!ELEMENT resolve (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>
<!ATTLIST resolve
variable CDATA #REQUIRED
args CDATA #IMPLIED>
Этот элемент изменяет проверяемый объект для всех своих подэлементов, заменяя его объектом, на который указывает переменная в атрибуте variable. Если разрешить переменную невозможно, то при вычислении выражения возбуждается ситуация ExpressionException. Для объединения подэлементов выражения with используется операция and.
<!ELEMENT adapt (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>
<!ATTLIST adapt
type CDATA #REQUIRED>
Данный элемент используется для адаптации выбранного объекта к типу, указанному в атрибуте type. Если адаптер или указанный тип еще не загружены, выражение возвращает NOT_LOADED. Если имя типа вообще не существует, то при вычислении выражения возбуждается ситуация ExpressionException. Для объединения подэлементов выражения adapt используется операция and.
<!ELEMENT iterate (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>
<!ATTLIST iterate
operator (or|and) >
Этот элемент используется для выполнения итераций с переменной, относящейся к типу java.util.Collection. Если тип выбранного объекта - не java.util.Collection, то при вычислении этого выражения возбуждается ситуация ExpressionException.
Базовое определение меню выглядит следующим образом.
<menu id=
"com.mycompany.myplugin.projection"
label=
"%Folding.label"
>
<location mnemonic=
"%Folding.label.mnemonic"
>
<part id=
"AntEditor"
>
<popup id=
"#RulerContext"
path=
"rest"
/>
</part>
</location>
</menu>
В этом примере разработчик модуля вносит дополнения во все компоненты, являющиеся подклассом или реализацией данного типа. Это позволяет, например, внести некоторые дополнения во все текстовые редакторы.
<menu id=
"com.mycompany.myplugin.textEditorMenu"
label=
"Text Commands"
>
<location mnemonic=
"X"
>
<part class=
"AbstractTextEditor"
>
<popup id=
"#RulerContext"
path=
"rest"
/>
</part>
</location>
</menu>
С меню можно связать справку.
<menu id=
"com.mycompany.myplugin.RunWithConfigurationAction"
label=
"Run With Configuration"
helpContextId=
"run_with_configuration_context"
>
<location>
<bar />
</location>
</menu>
В меню можно определять логические группы. Эти логические группы могут быть видимыми (то есть, до и после них вычерчиваются разделители) и невидимыми.По умолчанию логические группы являются видимыми.
<group id=
"com.mycompany.myplugin.stepGroup"
>
<location>
<bar path=
"org.eclipse.ui.run"
/>
</location>
</group>
<group id=
"com.mycompany.myplugin.stepIntoGroup"
separatorsVisible=
"false"
>
<location>
<bar path=
"org.eclipse.ui.run"
/>
</location>
</group>
Можно помещать меню, группы, элементы и виджеты в несколько расположений.
<item id=
"com.mycompany.myplugin.ToggleStepFilters"
commandId=
"com.mycompany.myplugin.ToggleStepFilters"
>
<location mnemonic=
"%mnemonic"
>
<bar path=
"org.eclipse.ui.run/emptyStepGroup"
/>
</location>
<location>
<part id=
"org.eclipse.debug.ui.DebugView"
>
<bar type=
"trim"
path=
"renderGroup"
/>
</part>
</location>
<location mnemonic=
"%mnemonic"
>
<part id=
"org.eclipse.debug.ui.DebugView"
>
<popup path=
"renderGroup"
/>
</part>
</location>
</item>
Если для всплывающего элемента не задан ИД и родительский элемент компонента, тогда он применяется ко всем контекстным меню, зарегистрированным в рабочей среде. Это аналогично поведению прежних дополнений объектов. Аналогично, всплывающий элемент верхнего уровня с заданным ИД затронет все контекстные меню, зарегистрированные с данным именем.
<item id=
"com.mycompany.myplugin.ObjectContribution"
commandId=
"com.mycompany.myplugin.ObjectContribution"
>
<location>
<popup path=
"additions"
/>
</location>
</item>
Иногда может потребоваться управлять областью видимости элемента. В то время как обычно требуется поддерживать стабильность разметки
меню и панелей инструментов, иногда желательно скрыть элементы, которые не требуются немедленно. Это в особенности относится к
контекстным меню, объем которых ограничен. В этом случае следует определить элемент visibleWhen
. Этот элемент
практически идентичен элементам activeWhen
и enabledWhen
, определенным в точке расширения обработчиков.
<item id=
"com.mycompany.myplugin.ConvertToWatchExpression"
commandId=
"com.mycompany.myplugin.ConvertToWatchExpression"
>
<location mnemonic=
"%mnemonic"
>
<part id=
"org.eclipse.debug.ui.DebugView"
>
<popup path=
"additions"
/>
</part>
</location>
<visibleWhen>
<with variable=
"selection"
>
<iterate operator=
"and"
>
<not>
<instanceof value=
"IWatchExpression"
/>
</not>
<instanceof value=
"IExpression"
/>
</iterate>
</with>
</visibleWhen>
</item>
Самый простой способ сделать элемент видимым - это включить его обработчик. Это позволяет сделать определенный элемент синтаксиса.
В элементе visibleWhen
существует атрибут checkEnabled
.
<item id=
"com.mycompany.myplugin.compareWithPatch"
commandId=
"com.mycompany.myplugin.compareWithPatch"
>
<location mnemonic=
"%mnemonic"
>
<part id=
"MyPart"
>
<popup path=
"additions"
/>
</part>
</location>
<visibleWhen checkEnabled=
"true"
/>
</item>
Любой элемент, связанный с командой, может включать значения параметра. Если параметр данного идентификатора не определен, это вызовет ошибку. Если элемент не имеет команды, это также вызовет ошибку.
<item id=
"com.mycompany.myplugin.RunHistory"
commandId=
"com.mycompany.myplugin.RunHistory"
>
<location>
<bar path=
"org.eclipse.ui.run"
/>
</location>
<parameter name=
"index"
value=
"1"
/>
</item>
Можно также задать относительное упорядочение. Это можно сделать с помощью атрибута order элемента расположения.
Атрибут order может иметь следующие значения: start
(поместить элемент в начале контейнера); end (поместить
элемент в конце контейнера); after
(поместить элемент после сестринского элемента, ИД которого соответствует ref
);
и before
(поместить элемент перед сестринским элементом, ИД которого соответствует ref
). К любому типу
элементов меню можно применить относительное упорядочение.
<item id=
"com.mycompany.myplugin.MyFirstItem"
commandId=
"com.mycompany.myplugin.MyFirstCommand"
>
<location>
<order position=
"start"
/>
<bar path=
"org.eclipse.ui.run"
/>
</location>
</item>
<item id=
"com.mycompany.myplugin.MySecondItem"
commandId=
"com.mycompany.myplugin.MySecondCommand"
>
<location>
<order position=
"after"
relativeTo=
"com.mycompany.myplugin.MyFirstItem"
/>
<bar path=
"org.eclipse.ui.run"
/>
</location>
</item>
Если требуется прямой доступ к виджетам (например, для вывода поля со списком), то можно использовать элемент widget
.
К сожалению, это означает, что если элемент виджета становится видимым в пользовательском интерфейсе, то это приводит к загрузке модуля.
<widget id=
"com.mycompany.myplugin.MyComboBoxSimple"
class=
"com.mycompany.myplugin.MyComboBox"
>
<location>
<bar type=
"trim"
path=
"myGroup"
/>
</location>
</widget>
<widget id=
"com.mycompany.myplugin.MyComboBoxParameterized1"
class=
"com.mycompany.myplugin.MyComboBox:a,b,c"
>
<location>
<bar type=
"trim"
path=
"myGroup"
/>
</location>
</widget>
<widget id=
"com.mycompany.myplugin.MyComboBoxParameterized2"
>
<class class=
"com.mycompany.myplugin.MyComboBox"
>
<parameter name=
"list"
value=
"a,b,c"
/>
<parameter name=
"selected"
value=
"c"
/>
<parameter name=
"editable"
value=
"false"
/>
</class>
<location>
<bar type=
"trim"
path=
"myGroup"
/>
</location>
</widget>
Для внесения дополнений во врезку в рабочей среде можно также использовать виджеты. В следующем примере определяется новый виджет 'HeapStatus', который по умолчанию должен быть помещен непосредственно после врезки строки состояния (а именно, в нижней части окна рабочей среды). Дополнительная информация о предопределенных группах приведена в описании элемента 'bar'.
Обратите внимание, что 'groups' (группы) врезки могут быть перемешены в другие области врезки. relativeTo
в информации
о расположении предполагает, что упоминаемая группа находится в расположении по умолчанию при определении нового расположения врезки.
В общем, предполагается, что участники, вносящие дополнения в этот тип, будут создавать собственную группу для содержания нового
виджета, что позволит изменять расположение данного элемента врезки независимо от других элементов врезки. Одним существенным
исключением является группа 'status'.
<extension point=
"org.eclipse.ui.menus"
>
<group id=
"TestTrimAPI.heapStatusGroup"
separatorsVisible=
"true"
>
<location>
<bar type=
"trim"
/>
<order position=
"after"
relativeTo=
"status"
/>
</location>
</group>
<widget class=
"HeapStatusWidget"
id=
"TestTrimAPI.HeapStatus"
>
<location>
<bar path=
"heapStatusGroup"
type=
"trim"
/>
</location>
<layout fillMajor=
"false"
fillMinor=
"true"
/>
</widget>
</extension>
IWorkbenchPartSite.registerContextMenu
.
Copyright (c) 2005 IBM Corporation и другие.
Все права защищены.
Эта программа и сопутствующие материалы распространяются на условиях Eclipse Public License v1.0, поставляемой вместе с продуктом и доступной на Web-сайте
http://www.eclipse.org/legal/epl-v10.html