Menus Pop-up

org.eclipse.ui.popupMenus

Esse ponto de extensão é utilizado para incluir novas ações nos menus de contexto pertencentes a outros plug-ins. As contribuições da ação podem ser feitas sobre um tipo de objeto especificado (objectContribution) ou sobre um menu de contexto específico de uma parte de visualização ou de editor (viewerContribution). Ao utilizar objectContribution, a contribuição aparecerá em todos os menus de contexto da parte de exibição ou de editor em que objetos do tipo especificado são selecionados. Em contraste, utilizando viewerContribution, a contribuição aparecerá somente no menu de contexto da parte de exibição ou do editor especificada, independentemente da seleção.

Quando a seleção é heterogênea, a contribuição será aplicada se registrada em oposição a um tipo comum da seleção, se possível. Se uma correspondência não for possível, a correspondência em relação a super classes e super interfaces será tentada.

A seleção pode ser futuramente limitada por meio da utilização de um filtro de nome. Se utilizado, todos os objetos na seleção devem corresponder ao filtro a fim de se aplicarem à contribuição.

Ações individuais em uma contribuição de objeto podem utilizar o atributo enablesFor, para especificar se o mesmo deve se aplicar somente para tipo de seleção simples, múltipla ou para qualquer outro tipo de seleção.

Se esses mecanismos de filtragem forem inadequados, uma contribuição de ação poderá utilizar o mecanismo filtro. Nesse caso os atributos do objeto de destino são descritos em uma série de pares nome-valor. Os atributos que aplicam-se à seleção são específicos dos tipos e além do domínio do próprio workbench, de modo que o workbench delegará a filtragem nesse nível na seleção real.

A ativação e/ou a visibilidade de uma ação podem ser definidas utilizando os elementos enablement e visibility, respectivamente. Esses dois elementos contêm uma expressão booleana que é avaliada para determinar a ativação e/ou visibilidade.

A sintaxe é a mesma para os elementos enablement e visibility. Ambos contêm apenas uma sub-elemento de expressão booleana. No caso mais simples, isso será um elemento objectClass, objectState, pluginState ou systemProperty. No caso mais complexo, os elementos and, or e not podem ser combinados para formar uma expressão booleana. Os elementos and e or devem conter 2 sub-elementos. O elemento not deve conter apenas 1 sub-elemento.

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

Esse elemento é utilizado para definir um grupo de ações e/ou menus para quaisquer menus de contexto do visualizador para os quais os objetos do tipo especificado são selecionados.



<!ELEMENT viewerContribution (visibility?, menu* , action*)>

<!ATTLIST viewerContribution

id       CDATA #REQUIRED

targetID CDATA #REQUIRED>

Esse elemento é utilizado para definir um grupo de ações e/ou menus para um menu de contexto da parte de exibição ou editor específico.



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

Esse elemento define uma ação que o usuário pode chamar na UI.



<!ELEMENT filter EMPTY>

<!ATTLIST filter

name  CDATA #REQUIRED

value CDATA #REQUIRED>

Esse elemento é utilizado para avaliar o estado do atributo de cada objeto na seleção atual. Uma correspondência ocorrerá apenas se cada objeto na seleção tiver o estado de atributo especificado. Cada objeto na seleção deve implementar, ou se adaptar a, org.eclipse.ui.IActionFilter.



<!ELEMENT menu (separator+ , groupMarker*)>

<!ATTLIST menu

id    CDATA #REQUIRED

label CDATA #REQUIRED

path  CDATA #IMPLIED>

Esse elemento é utilizado para definir um novo menu.



<!ELEMENT separator EMPTY>

<!ATTLIST separator

name CDATA #REQUIRED>

Esse elemento é utilizado para criar um separador de menu no novo menu.



<!ELEMENT groupMarker EMPTY>

<!ATTLIST groupMarker

name CDATA #REQUIRED>

Esse elemento é utilizado para criar um grupo nomeado no novo menu. Não há representação visual no novo menu, diferentemente do elemento separator.



<!ELEMENT selection EMPTY>

<!ATTLIST selection

class CDATA #REQUIRED

name  CDATA #IMPLIED>

Esse elemento é utilizado para ajudar a determinar a ativação da ação com base na seleção atual. É ignorado se o elemento enablement for especificado.



<!ELEMENT enablement (and | or | not | objectClass | objectState | pluginState | systemProperty)>

Esse elemento é utilizado para definir a ativação da extensão.



<!ELEMENT visibility (and | or | not | objectClass | objectState | pluginState | systemProperty)>

Esse elemento é utilizado para definir a visibilidade da extensão.



<!ELEMENT and (and | or | not | objectClass | objectState | pluginState | systemProperty)>

Esse elemento representa uma operação booleana AND como resultado da avaliação de duas expressões de subelementos.



<!ELEMENT or (and | or | not | objectClass | objectState | pluginState | systemProperty)>

Esse elemento representa uma operação booleana OR como resultado da avaliação de duas expressões de subelementos.



<!ELEMENT not (and | or | not | objectClass | objectState | pluginState | systemProperty)>

Esse elemento representa uma operação booleana NOT no resultado da avaliação de expressões de subelementos.



<!ELEMENT objectClass EMPTY>

<!ATTLIST objectClass

name CDATA #REQUIRED>

Esse elemento é utilizado para avaliar a classe ou interface de cada objeto na seleção atual. Se cada objeto na seleção implementar a classe ou interface especificada, a expressão será avaliada como verdadeira.



<!ELEMENT objectState EMPTY>

<!ATTLIST objectState

name  CDATA #REQUIRED

value CDATA #REQUIRED>

Esse elemento é utilizado para avaliar o estado do atributo de cada objeto na seleção atual. Se cada objeto na seleção possuir o estado de atributo especificado, a expressão será avaliada como verdadeira. Para avaliar esse tipo de expressão, cada objeto na seleção deve implementar ou se adaptar à interface org.eclipse.ui.IActionFilter.



<!ELEMENT pluginState EMPTY>

<!ATTLIST pluginState

id    CDATA #REQUIRED

value (installed|activated) "installed">

Esse elemento é utilizado para avaliar o estado de um plug-in. O estado do plug-in pode ser um dos seguintes: installed (equivalente ao conceito OSGi de "resolved") ou activated (equivalente ao conceito OSGi de "active").



<!ELEMENT systemProperty EMPTY>

<!ATTLIST systemProperty

name  CDATA #REQUIRED

value CDATA #REQUIRED>

Esse elemento é utilizado para avaliar o estado de algumas propriedades do sistema. O valor da propriedade é recuperado de java.lang.System.



<!ELEMENT enablement (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>

Um elemento 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>

Esse elemento é utilizado para executar uma verificação instanceof 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 retornará 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>

Esse elemento altera o objeto para ser inspecionado para obter todo seu elemento filho para o objeto referenciado pela determinada variável. 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>

Esse elemento altera o objeto para ser inspecionado para obter todo seu elemento filho para o objeto referenciado pela determinada variável. 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>

Esse 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 referenciado ainda não estiver carregado. Ele lançará um ExpressionException durante a avaliação se o nome do tipo não existir ainda. 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 iterar sobre 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.



A seguir um exemplo de um ponto de extensão do menu pop-up:

   

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

"&amp;XYZ Java Tools"

>

<separator name=

"group1"

/>

</menu>

<action id=

"com.xyz.runXYZ"

label=

"&amp;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=

"&amp;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>

No exemplo acima, a ação de contribuição de objeto especificada somente irá ativar para uma única seleção (atributo enablesFor). Além disso, cada objeto na seleção deve implementar a interface especificada (IFile) e deve ser um arquivo tipo Java. Essa ação será incluída dentro de um sub-menu previamente criado. Essa contribuição será efetiva em qualquer exibição que tenha a seleção solicitada.

Ao contrário, a contribuição do visualizador acima somente aparecerá no menu de contexto da exibição Tarefas e não será afetada pela seleção na exibição.

A seguir encontra-se um exemplo do mecanismo de filtro. Nesse caso, a ação somente aparecerá para IMarkers que são completos e têm alta prioridade.

   

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

A seguir encontra-se outro exemplo da utilização do elemento visibility:

   

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

"&amp;Show XYZ"

style=

"push"

menubarPath=

"additions"

icon=

"icons/showXYZ.gif"

helpContextId=

"com.xyz.show_action_context"

class=

"com.xyz.actions.XYZShowActionDelegate"

>

</action>

</viewerContribution>

</extension>

No exemplo acima, a ação especificada aparecerá como um item de menu no menu de contexto da exibição Tarefa, mas somente se o plug-in "com.xyz" estiver ativo e a propriedade do sistema especificado for definida como true.

O valor do atributo de ação class deve ser um nome completo de uma classe Java que implemente org.eclipse.ui.IObjectActionDelegate no caso das contribuições do objeto, org.eclipse.ui.IViewActionDelegate para contribuições de menus de contexto que pertençam às exibições ou org.eclipse.ui.IEditorActionDelegate para contribuições de menus de contexto que pertençam aos editores. Em todos os casos, a classe de implementação é carregada o mais tarde possível para evitar o carregamento de todo o plug-in antes que isso seja realmente necessário.

Nota: Para compatibilidade inversa, org.eclipse.ui.IActionDelegate pode ser implementado para contribuições de objeto.

A extensão de menu de contexto dentro de uma parte será possível apenas quando a parte de destino publicar um menu para extensão. Isso é altamente encorajado, pois aprimora a extensibilidade do produto. Para realizar isso, cada parte deve publicar quaisquer menus de contexto que são definidos chamando IWorkbenchPartSite.registerContextMenu. Após isso ser feito, o workbench irá inserir automaticamente quaisquer extensões de ações existentes.

Um ID de menu deve ser fornecido para cada menu registrado. Para consistência entre as partes, a seguinte estratégia deve ser adotada por todos os implementadores de partes.

Qualquer menu de contexto que esteja registrado no workbench também deve conter um ponto de inserção padrão com ID IWorkbenchActionConstants.MB_ADDITIONS. Outros plug-ins utilizarão esse valor como um ponto de referência para inserção. O ponto de inserção pode ser definido pela adição de um GroupMarker ao menu em uma localização apropriada para inserção.

Um objeto no workbench que é a seleção em um menu de contexto pode definir um org.eclipse.ui.IActionFilter. Essa é uma estratégia de filtragem que pode executar filtragem específica de tipos. O workbench recuperará o filtro para a seleção testando se ela implementa IActionFilter. Se isso falhar, o workbench solicitará um filtro por meio do mecanismo IAdaptable.

Os rótulos de ação e de menu podem conter caracteres especiais que codificam mnemônicos os quais são especificados utilizando o caracter e comercial ('&') em frente de um caractere selecionado no texto traduzido. Uma vez que o e comercial não é permitido em cadeias XML, utilize a entidade de caractere &amp;.

Se duas ou mais ações contribuírem com um menu por uma única extensão, as ações aparecerão na ordem inversa de como elas serão listadas no arquivo plugin.xml. Esse comportamento é admitidamente não-intuitivo. Entretanto, ele foi descoberto depois que a API da Plataforma Eclipse tinha sido congelada. Alterar o procedimento agora iria interromper cada plug-in que segue o comportamento existente.

Os elementos selection e enablement são mutuamente exclusivos. O elemento enablement pode substituir o elemento selection utilizando os sub-elementos objectClass e objectState. Por exemplo, o seguinte:

 

<selection class=

"org.eclipse.core.resources.IFile"

name=

"*.java"

>

</selection>

pode ser expresso utilizando:
 

<enablement>

<and>

<objectClass name=

"org.eclipse.core.resources.IFile"

/>

<objectState name=

"extension"

value=

"java"

/>

</and>

</enablement>

As exibições do workbench possuem menus de contexto internos que já vêm carregados com várias ações. Os plug-ins podem contribuir para esses menus. Se um visualizador tiver reservado slots para essas contribuições e eles se tornarem públicos, os nomes dos slots podem ser utilizados como caminhos. De outro modo, as ações e os sub-menus serão incluídos ao final do menu pop-up.