Меню

org.eclipse.ui.menus

3.2

С помощью этой точки расширения разработчик модуля может определять меню, разделители, логические группы и элементы меню -- в любом месте приложения, от строк состояния до контекстных меню. Можно также определить наборы таких дополнений (то есть, наборов действий); конечный пользователь может включать и выключать эти наборы действий. В общих чертах, точка расширения меню содержит все элементы представления (за исключением значков) для внесения в любое меню или ограниченную область в 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, в зависимости от размещения. Связанные с этим элементом текст и изображение будут извлечены из команды.



<!ELEMENT menu (location* , visibleWhen?)>

<!ATTLIST menu

id    CDATA #REQUIRED

label CDATA #IMPLIED>

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

Меню может содержать только группы.



<!ELEMENT group (location*)>

<!ATTLIST group

id                CDATA #REQUIRED

separatorsVisible (true | false) "true">

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

Группа может содержать меню, элементы и другие группы.



<!ELEMENT widget (location* , class? , visibleWhen? , layout?)>

<!ATTLIST widget

id    CDATA #REQUIRED

class CDATA #REQUIRED>

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



<!ELEMENT layout EMPTY>

<!ATTLIST layout

fillMajor (true | false)

fillMinor (true | false) >

Этот элемент можно использовать для указания различных опций размещения для элементов, добавленных в расположения trim.



<!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, то он указывает на меню или врезку этого компонента.



<!ELEMENT class (parameter*)>

<!ATTLIST class

class CDATA #REQUIRED>

Элемент класса, поддерживающий исполняемый синтаксис расширения для элементов widget и dynamic.



<!ELEMENT visibleWhen (not | or | and | instanceof | test | systemTest | equals | count | with | resolve | adapt | iterate)>

<!ATTLIST visibleWhen

checkEnabled (true | false) "false">

Управляет областью видимости данного элемента.



<!ELEMENT part (popup | bar)>

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

Управляет положением меню, группы, элемента или виджета в определенном расположении.



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