Esse ponto de extensão permite que o desenvolvedor de plug-in defina menus, separadores, grupos lógicos e itens de menu -- aparecendo em outros locais do aplicativo, desde linhas de status a menus de contexto. Ele permite também a definição de conjuntos de contribuições (por exemplo, conjuntos de ações); esses conjuntos de ações podem ser ativados ou desativados pelo usuário final. Resumidamente, o ponto de extensão de menus contém todos os elementos de apresentação (exceto os ícones) para contribuir com qualquer menu ou área de ajuste no Eclipse.
Cada elemento desse ponto de extensão recebe um identificador exclusivo. Isso ocorre para que esses elementos possam ser referidos em outros locais sem precisar determinar novamente o elemento. Por exemplo, o identificador poderá ser necessário para solicitar ou definir um conjunto de ações. Além disso, isso permite que desenvolvedores de plug-in de terceiros coloquem esses elementos em novos locais na interface, conforme apropriado.
NOTA: Na versão 3.2, a única parte desse mecanismo de extensão que foi implementada é aquela parte associada às contribuições 'trim'. A tentativa de incluir itens, menus, barras de ferramentas ou entradas de linha de status funcionará como um NO-OP.
<!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>
Item pode ser um item de menu ou de ajuste, dependendo de onde é colocado. O texto e a imagem associados ao item serão extraídos do comando.
org.eclipse.ui
poderá ser chamado de
org.eclipse.ui.item1
.<!ELEMENT menu (location* , visibleWhen?)>
<!ATTLIST menu
id CDATA #REQUIRED
label CDATA #IMPLIED>
Um menu pode aparecer anexado a um item de ferramenta ou em outro local em um menu de visualização, de contexto ou na barra de menus de nível superior. Livremente, o desenvolvedor de plug-in pode assumir que há um menu e uma barra de ferramentas para cada visualização, e que existe barra de menus de nível superior. Menus de contexto devem ser registrados por programa antes que possam ser utilizados (consulte Informações de API).
Um menu só pode conter grupos.
org.eclipse.ui
poderá ser chamado
de org.eclipse.ui.menu1
.<!ATTLIST group
id CDATA #REQUIRED
separatorsVisible (true | false) "true">
Um grupo lógico. Pode ser visível (por exemplo, separadores são exibidos antes e depois, conforme apropriado) ou invisível. Por padrão, grupos lógicos são visíveis.
Um grupo pode conter menus, itens e outros grupos.
org.eclipse.ui
poderá ser chamado de
org.eclipse.ui.group1
.<!ELEMENT widget (location* , class? , visibleWhen? , layout?)>
<!ATTLIST widget
id CDATA #REQUIRED
class CDATA #REQUIRED>
Um elemento de menu ou ajuste que recebe acesso direto aos widgets. Por exemplo, isso pode ser utilizado para renderizar uma caixa de combinação. Infelizmente, isso significa que se um elemento de widget se tornar visível na interface com o usuário, isso levará ao carregamento do plug-in. Utilize esse elemento com cuidado, pois ele pode causar problemas de desempenho. Isso também poderá causar problemas, por exemplo, no suporte de macro, em scripts e em quase todos os demais mecanismos baseados em comando. Quando utilizado como ajuste, o widget fará com que o plug-in seja carregado somente quando ele se tornar visível na UI.
org.eclipse.ui
poderá ser chamado de
org.eclipse.ui.widget1
.IWorkbenchWidget
. Os clientes podem optar pela implementação padrão: AbstractWorkbenchTrimWidget
. Essa implementação usa o método 'init' e armazena em cache o resultado do uso por meio do método getWorkbenchWindow
.<!ELEMENT layout EMPTY>
<!ATTLIST layout
fillMajor (true | false)
fillMinor (true | false) >
Esse elemento pode ser utilizado para especificar várias opções de layout para elementos
incluídos em locais de ajuste
.
false
.false
.<!ELEMENT location (order? , (bar | part | popup))>
<!ATTLIST location
mnemonic CDATA #IMPLIED
imageStyle CDATA #IMPLIED>
Um local no qual um menu
, grupo
, item
ou
widget
pode aparecer. Esse elemento é utilizado para controlar
informações específicas de local.
<!ELEMENT bar EMPTY>
<!ATTLIST bar
type (menu|trim)
path CDATA #IMPLIED>
Um elemento folha em um local. Isso pode ser a barra de menus o a área de ajuste. Se não
qualificado, isso indica o ajuste ou a barra de menus de nível superior. Se qualificado
com um elemento de parte
, isso indica menu ou ajuste da parte.
menu
ou ajuste
. Se contribuindo com o menu, o item será
originado de uma estrutura de widget. Em geral, isso significa que o uso de elementos de
widget não faz muito sentido, e um ícone para um comando de item não é estritamente
necessário. O valor padrão é menu
.
Se contribuindo para o ajuste
, a barra geralmente não exigirá um comando
ou um ícone; ela deverá ser preenchida com um widget que exibe as informações do ajuste.
No ajuste, o ambiente de trabalho define cinco grupos gerais que correspondem a várias posições em torno da janela:
vertical1
.'/'
como caractere separador.<!ATTLIST class
class CDATA #REQUIRED>
Um elemento de classe que suporta a sintaxe de análise de extensão executável para os
elementos widget
e dinâmico
.
IExecutableExtension
.<!ELEMENT visibleWhen (not | or | and | instanceof | test | systemTest | equals | count | with | resolve | adapt | iterate)>
<!ATTLIST visibleWhen
checkEnabled (true | false) "false">
Controla a visibilidade do elemento determinado.
true
,
não deverá haver subelementos. Isso apenas verifica o estado ativado do comando e torna
visível o elemento corresponde, se o comando estiver ativado.<!ATTLIST part
id CDATA #IMPLIED
class CDATA #IMPLIED>
Um elemento em um local. Isso qualifica o local a referir-se a uma parte específica do ambiente de trabalho. Isso pode ser uma visualização ou um editor. A qualificação pode utilizar o nome de classe da parte (incluindo herança) ou pode referir-se ao identificador da visualização ou do editor.
Apenas um de id
e classe
pode ser especificado.
<!ELEMENT parameter EMPTY>
<!ATTLIST parameter
name CDATA #REQUIRED
value CDATA #REQUIRED>
Um parâmetro para uma extensão executável ou um comando - dependendo de onde ele aparece na extensão.
<!ELEMENT order EMPTY>
<!ATTLIST order
position (start|end|before|after)
relativeTo CDATA #IMPLIED>
Controla a posição de um menu, grupo, item ou widget em um determinado local.
Esse atributo aceita os seguintes valores: start
(colocar o elemento no
início do contêiner); end
(colocar o elemento no final de seu
contêiner); after
(colocar o elemento após o elemento irmão cujo id
corresponde a ref
); e before
(colocar o elemento antes do
elemento irmão cujo id corresponde a ref
). A ordem
relativa pode ser aplicada a qualquer tipo de elemento de menu.
No caso de conflitos, o Eclipse escolherá uma ordem arbitrária. A única garantia é que, no caso de um conflito, a ordem permanecerá a mesma desde que seja mantido o seguinte:
posição
for antes
ou
após
.<!ELEMENT popup EMPTY>
<!ATTLIST popup
id CDATA #IMPLIED
path CDATA #IMPLIED>
Parte de um local. Indica que o menu, grupo, item ou widget deve aparecer no menu pop-up.
<!ELEMENT enablement (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>
Um elemento de raiz genérico. O elemento pode ser utilizado dentro de um ponto de extensão para definir sua expressão de ativação. Os filhos de uma expressão de ativação são combinados utilizando o operador and.
<!ELEMENT not (not | and | or | instanceof | test | systemTest | equals | count | with | resolve | adapt | iterate)>
Esse elemento representa uma operação NOT como resultado da avaliação da expressão do subelemento.
<!ELEMENT and (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>
Esse elemento representa uma operação AND como resultado da avaliação de todas as expressões dos subelementos.
<!ELEMENT or (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>
Esse elemento representa uma operação OR como resultado da avaliação de todas as expressões do subelemento.
<!ELEMENT instanceof EMPTY>
<!ATTLIST instanceof
value CDATA #REQUIRED>
Este elemento é utilizado para executar uma instância de verificação do objeto em foco. A expressão retornará EvaluationResult.TRUE se o tipo do objeto for um subtipo do tipo especificado pelo valor do atributo. Caso contrário, EvaluationResult.FALSE será retornado.
<!ELEMENT test EMPTY>
<!ATTLIST test
property CDATA #REQUIRED
args CDATA #IMPLIED
value CDATA #IMPLIED>
Esse elemento é utilizado para avaliar o estado da propriedade do objeto em foco. O conjunto de propriedades testáveis pode ser estendido utilizando o ponto de extensão do testador de propriedade. A expressão de teste retornará EvaluationResult.NOT_LOADED se o testador de propriedade que realiza o teste real ainda não estiver carregado.
<!ELEMENT systemTest EMPTY>
<!ATTLIST systemTest
property CDATA #REQUIRED
value CDATA #REQUIRED>
Testa uma propriedade do sistema chamando o método System.getProperty e compara o resultado com o valor especificado por meio do atributo de valor.
<!ELEMENT equals EMPTY>
<!ATTLIST equals
value CDATA #REQUIRED>
Esse elemento é utilizado para executar uma verificação equals do objeto em foco. A expressão retorna EvaluationResult.TRUE se o objeto for igual ao valor fornecido pelo valor do atributo. Caso contrário, EvaluationResult.FALSE será retornado.
<!ELEMENT count EMPTY>
<!ATTLIST count
value CDATA #REQUIRED>
Esse elemento é utilizado para testar o número de elementos em uma coleta.
<!ELEMENT with (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>
<!ATTLIST with
variable CDATA #REQUIRED>
O elemento altera o objeto, a ser inspecionado para todos os seus elementos filho, para o objeto referido pela variável fornecida. Se a variável não puder ser resolvida, a expressão lançará um ExpressionException ao avaliá-la. Os filhos de uma expressão são combinados utilizando o operador and.
<!ELEMENT resolve (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>
<!ATTLIST resolve
variable CDATA #REQUIRED
args CDATA #IMPLIED>
O elemento altera o objeto, a ser inspecionado para todos os seus elementos filho, para o objeto referido pela variável fornecida. Se a variável não puder ser resolvida, a expressão lançará um ExpressionException ao avaliá-la. Os filhos de uma expressão são combinados utilizando o operador and.
<!ELEMENT adapt (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>
<!ATTLIST adapt
type CDATA #REQUIRED>
Este elemento é utilizado para adaptar o objeto em foco ao tipo especificado pelo tipo de atributo. A expressão será retornada sem carregar, se o adaptador ou o tipo referido ainda não estiver carregado. Isso lança um ExpressionException durante a avaliação se o nome do tipo não existir. Os filhos de uma expressão de adaptação são combinados utilizando o operador and.
<!ELEMENT iterate (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>
<!ATTLIST iterate
operator (or|and) >
Esse elemento é utilizado para repetir uma variável do tipo java.util.Collection. Se o objeto em foco não for do tipo java.util.Collection uma ExpressionException será lançada durante a avaliação da expressão.
Uma definição de menu básica se parece com esta.
<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>
Neste exemplo, o desenvolvedor de plug-in está contribuindo com todas as partes que subclassificam ou implementam o tipo determinado. Isso permite, por exemplo, que algumas contribuições sejam incluídas em todos os editores de texto.
<menu id=
"com.mycompany.myplugin.textEditorMenu"
label=
"Text Commands"
>
<location mnemonic=
"X"
>
<part class=
"AbstractTextEditor"
>
<popup id=
"#RulerContext"
path=
"rest"
/>
</part>
</location>
</menu>
É possível associar a ajuda a um menu.
<menu id=
"com.mycompany.myplugin.RunWithConfigurationAction"
label=
"Run With Configuration"
helpContextId=
"run_with_configuration_context"
>
<location>
<bar />
</location>
</menu>
Em um menu, é possível definir grupos lógicos. Esses grupos lógicos podem ser visíveis (por exemplo, separadores são exibidos antes e depois, conforme apropriado) ou invisíveis. Por padrão, grupos lógicos são visíveis.
<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>
É possível colocar menus, grupo, itens e widgets em vários locais.
<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>
Se o elemento pop-up for especificado sem id e sem elemento de parte pai, ele será aplicado a qualquer menu de contexto registrado no ambiente de trabalho. Isso é semelhante ao comportamento das antigas contribuições de objeto. Da mesma forma, um elemento pop-up de nível superior com um id afetará qualquer menu de contexto registrado no nome determinado.
<item id=
"com.mycompany.myplugin.ObjectContribution"
commandId=
"com.mycompany.myplugin.ObjectContribution"
>
<location>
<popup path=
"additions"
/>
</location>
</item>
Às vezes, você pode desejar controlar a visibilidade de um item. Embora em geral seja
preferível manter a estabilidade no layout de menus e barras de ferramentas, às vezes é
desejável ocultar itens que não são de importância imediata. Isso é comprovado
especialmente em menus de contexto, em que o espaço é limitado. Nesse caso, você
definiria um elemento visibleWhen
. Esse elemento é quase idêntico aos
elementos activeWhen
e enabledWhen
definidos no
ponto de extensão de rotinas de tratamento.
<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>
O caso mais comum é simplesmente tornar algo visível quando sua rotina de tratamento for
ativada. Isso é tratado com cuidado sintático. Há um atributo checkEnabled
no elemento visibleWhen
.
<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>
Qualquer item associado a um comando pode incluir valores de parâmetro. Se o parâmetro do identificador determinado não for definido, isso será um erro. Se o item não tiver um comando, isso também será um erro.
<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>
Também é possível especificar ordens relativas. Isso é feito utilizando o atributo
de ordem no elemento de local. O atributo de ordem aceita os seguintes valores:
start
(colocar o elemento no início do contêiner); end (colocar
o elemento no final de seu contêiner); after
(colocar o elemento após o
elemento irmão cujo id corresponde a ref
); e before
(colocar o
elemento antes do elemento irmão cujo id corresponde a ref
). A ordem
relativa pode ser aplicada a qualquer tipo de elemento de menu.
<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>
Se você precisar de acesso direto aos widgets (por exemplo, para renderizar uma caixa de
combinação), poderá utilizar um elemento widget
. Infelizmente, isso
significa que se um elemento de widget se tornar visível na interface com o usuário, isso
levará ao carregamento do plug-in.
<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>
Você também pode utilizar widgets para contribuir no ajuste do ambiente de trabalho. O exemplo a seguir define um novo widget 'HeapStatus' que deverá ser colocado, por padrão, imediatamente após o ajuste de linha de status (isto é, na parte inferior da janela do ambiente de trabalho). Consulte a descrição do elemento 'barra' para obter mais informações sobre grupos predefinidos.
Observe que os 'grupos' de ajuste podem ser relocados para outras áreas de
ajuste. A informação de local relativeTo
presumirá que o grupo referido
está em sua posição padrão quando determinar o novo local de ajuste. Em geral, espera-se
que os contribuidores desse tipo criem seu próprio grupo para hospedar o novo widget,
permitindo que o elemento de ajuste seja relocado independentemente dos outros elementos
de ajuste. Uma exceção notável a isso seria o grupo '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
.
Direitos Autorais (c) 2005 IBM Corporation e outros.
Todos os direitos reservados. Este programa e os materiais fornecidos com ele são
disponibilizados sob os termos da Licença Pública do Eclipse v1.0 que acompanha
esta distribuição e está disponível em
http://www.eclipse.org/legal/epl-v10.html