Menus

org.eclipse.ui.menus

3.2

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.



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



<!ELEMENT group (location*)>

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



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



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



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



<!ELEMENT class (parameter*)>

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



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



<!ELEMENT part (popup | bar)>

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



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

Para registrar um menu de contexto, utilize os métodos IWorkbenchPartSite.registerContextMenu.