Menus Emergentes

org.eclipse.ui.popupMenus

Este ponto de extensão é utilizado para adicionar novas acções aos menus de contexto que são propriedade de outros conectores. As contribuições de acções podem ser feitas contra um tipo de objecto específico (objectContribution) ou contra um menu de contexto específico de um componente de visualização ou editor (viewerContribution). Quando utilizar objectContribution, a colaboração irá aparecer em todos os menus contextuais do componente de visualização ou editor onde são seleccionados os objectos do tipo especificado. Em contraste, utilizando viewerContribution, a colaboração irá apenas aparecer no menu de contexto do componente de visualização ou de editor especificado, independentemente da selecção.

Quando a selecção é heterogénea, a colaboração será aplicada se for registada contra um tipo comum de selecção, se possível. Se não for possível uma correspondência directa, tenta-se uma correspondência contra super-classes e super-interfaces.

A selecção pode restringir-se ainda mais através do uso de um filtro de nome. Se utilizado, todos os objectos na selecção têm de corresponder ao filtro para aplicar a colaboração.

As acções individuais numa colaboração de objecto podem utilizar o atributo enablesFor para especificar se deve apenas aplicar-se a um tipo de selecção único, múltiplo ou qualquer outro tipo de selecção.

Se estes mecanismos de filtragem não forem adequados, uma colaboração de acção pode utilizar o mecanismo filter. Neste caso, os atributos do objecto de destino são descritos numa série de pares nome-valor. Os atributos que se aplicam à selecção são específicos do tipo e estão para além do domínio da própria área de trabalho, por isso, a área de trabalho irá delegar a filtragem neste nível para a verdadeira selecção.

A activação e/ou visibilidade de uma acção pode ser definida utilizando os elementos enablement e visibility, respectivamente. Estes dois elementos contêm uma expressão booleana que é avaliada para determinar a activação e/ou visibilidade.

A sintaxe é igual para os elementos enablement e visibility. Ambos contêm apenas um subelemento de expressão booleana. No caso mais simples, este 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. Tanto o elemento and como o elemento or têm de conter dois subelementos. O elemento not tem de conter apenas 1 subelemento.

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

Este elemento é utilizado para definir um grupo de acções e/ou menus para quaisquer menus contextuais do visualizador, para o qual são seleccionados os objectos do tipo especificado.



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

<!ATTLIST viewerContribution

id       CDATA #REQUIRED

targetID CDATA #REQUIRED>

Este elemento é utilizado para definir um grupo de acções e/ou menus para um menu de contexto do componente de visualização ou de 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>

Este elemento define uma acção que o utilizador pode invocar na UI.



<!ELEMENT filter EMPTY>

<!ATTLIST filter

name  CDATA #REQUIRED

value CDATA #REQUIRED>

Este elemento é utilizado para avaliar o estado do atributo de cada objecto na selecção actual. É uma correspondência apenas se cada objecto da selecção estiver no estado de atributo especificado. Cada objecto na selecção tem de implementar ou adaptar-se a org.eclipse.ui.IActionFilter.



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

<!ATTLIST menu

id    CDATA #REQUIRED

label CDATA #REQUIRED

path  CDATA #IMPLIED>

Este elemento é utilizado para definir um novo menu.



<!ELEMENT separator EMPTY>

<!ATTLIST separator

name CDATA #REQUIRED>

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



<!ELEMENT groupMarker EMPTY>

<!ATTLIST groupMarker

name CDATA #REQUIRED>

Este elemento é utilizado para criar um grupo designado no novo menu. Não tem qualquer representação visual no novo menu, ao contrário do elemento separator.



<!ELEMENT selection EMPTY>

<!ATTLIST selection

class CDATA #REQUIRED

name  CDATA #IMPLIED>

Este elemento é utilizado para ajudar a determinar a activação de acção, com base na selecção actual. É ignorado se o elemento enablement estiver especificado.



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

Este elemento é utilizado para definir a activação da extensão.



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

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



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

Este elemento representa uma operação AND booleana no resultado de avaliação das duas expressões de subelemento respectivas.



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

Este elemento representa uma operação OR booleana no resultado de avaliação das duas expressões de subelemento respectivas.



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

Este elemento representa uma operação NOT booleana no resultado de avaliação das expressões de subelemento respectivas.



<!ELEMENT objectClass EMPTY>

<!ATTLIST objectClass

name CDATA #REQUIRED>

Este elemento é utilizado para avaliar a classe ou interface de cada objecto na selecção actual. Se cada objecto da selecção implementar a classe ou interface especificadas, a expressão é avaliada como true.



<!ELEMENT objectState EMPTY>

<!ATTLIST objectState

name  CDATA #REQUIRED

value CDATA #REQUIRED>

Este elemento é utilizado para avaliar o estado do atributo de cada objecto na selecção actual. Se cada objecto da selecção possuir o estado de atributo especificado, a expressão é avaliada como true. Para avaliar este tipo de expressão, cada objecto na selecção tem de implementar ou adaptar-se à interface org.eclipse.ui.IActionFilter.



<!ELEMENT pluginState EMPTY>

<!ATTLIST pluginState

id    CDATA #REQUIRED

value (installed|activated) "installed">

Este elemento é utilizado para avaliar o estado de um conector. O estado do conector 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>

Este elemento é utilizado para avaliar o estado de alguma propriedade do sistema. O valor property é obtido a partir 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 a respectiva expressão de activação. Os elementos descendentes de uma expressão de activação são combinados com recurso ao operador and.



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

Este elemento representa uma operação NOT no resultado de avaliação da respectiva expressão de subelemento.



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

Este elemento representa uma operação AND no resultado de avaliação de todas as respectivas expressões de subelementos.



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

Este elemento representa uma operação OR no resultado de avaliação de todas as respectivas expressões de subelemento.



<!ELEMENT instanceof EMPTY>

<!ATTLIST instanceof

value CDATA #REQUIRED>

Este elemento é utilizado para desempenhar uma verificação instanceof do objecto em questão. A expressão devolve EvaluationResult.TRUE se o tipo do objecto for um subtipo do tipo especificado pelo valor do atributo. De outro modo, devolve EvaluationResult.FALSE.



<!ELEMENT test EMPTY>

<!ATTLIST test

property CDATA #REQUIRED

args     CDATA #IMPLIED

value    CDATA #IMPLIED>

Este elemento é utilizado para avaliar o estado de propriedade do objecto em questão. O conjunto de propriedades verificáveis pode ser alargado utilizando o ponto de extensão do dispositivo de testes de propriedade. A expressão do teste devolve EvaluationResult.NOT_LOADED se o dispositivo de testes de propriedade que está a fazer o teste ainda não estiver carregado.



<!ELEMENT systemTest EMPTY>

<!ATTLIST systemTest

property CDATA #REQUIRED

value    CDATA #REQUIRED>

Testa uma propriedade de sistema solicitando o método System.getProperty e compara o resultado com o valor especificado através do atributo value.



<!ELEMENT equals EMPTY>

<!ATTLIST equals

value CDATA #REQUIRED>

Este elemento é utilizado para desempenhar uma verificação equals do objecto em questão. A expressão devolve EvaluationResult.TRUE se o objecto for igual ao valor fornecido pelo atributo value. De outro modo, devolve EvaluationResult.FALSE.



<!ELEMENT count EMPTY>

<!ATTLIST count

value CDATA #REQUIRED>

Este elemento é utilizado para testar o número de elementos numa recolha.



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

<!ATTLIST with

variable CDATA #REQUIRED>

Este elemento altera o objecto a ser inspeccionado em todos os elementos descendentes, para o objecto referenciado pela dada variável. Se a variável não puder ser processada, a expressão apresenta ExpressionException quando estiver a fazer a avaliação. Os elementos descendentes de uma expressão with são combinados com recurso ao operador and.



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

<!ATTLIST resolve

variable CDATA #REQUIRED

args     CDATA #IMPLIED>

Este elemento altera o objecto a ser inspeccionado em todos os elementos descendentes, para o objecto referenciado pela dada variável. Se a variável não puder ser processada, a expressão apresenta ExpressionException quando estiver a fazer a avaliação. Os elementos descendentes de uma expressão with são combinados com recurso ao 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 objecto em questão ao tipo especificado pelo tipo do atributo. A expressão devolve not loaded se o adaptador ou o tipo referenciados ainda não estiverem carregados. Apresenta ExpressionException durante a avaliação se o nome do tipo não existir. Os elementos descendentes de uma expressão adapt são combinados com recurso ao operador and.



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

<!ATTLIST iterate

operator (or|and) >

Este elemento é utilizado para iterar numa variável que seja de tipo java.util.Collection. Se o objecto em questão não for do tipo java.util.Collection, surge ExpressionException durante a avaliação da expressão.



A seguir encontra-se um exemplo de um ponto de extensão de menu emergente:

   

<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 anterior, a acção de colaboração de objecto especificada será apenas activada para uma selecção única (atributo enablesFor). Além disso, cada objecto na selecção tem de implementar a interface especificada (IFile) e tem de ser um ficheiro Java. Esta acção será adicionada a um submenu previamente criado. Esta colaboração entrará em vigor em qualquer vista que tenha a selecção necessária.

Ao contrário, a colaboração do visualizador anterior irá aparecer apenas no menu de contexto da visualização Tasks, não sendo afectada pela selecção na visualização.

A seguir encontra-se um exemplo do mecanismo de filtro. Neste caso, a acção irá aparecer apenas para IMarkers que estão concluídos e têm uma prioridade elevada.

   

<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 um outro exemplo da utilização do elemento de visibilidade:

   

<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 anterior, a acção especificada irá aparecer como um artigo do menu no menu de contexto da visualização Tarefa, mas apenas se o conector "com.xyz" estiver activo e se a propriedade do sistema especificada estiver definida como true.

O valor do atributo de acção class tem de ser um nome de classe totalmente qualificado de uma classe Java que implemente org.eclipse.ui.IObjectActionDelegate, no caso de contribuições de objectos, org.eclipse.ui.IViewActionDelegate, no caso de contribuições para menus de contexto que pertencem a visualizações, ou org.eclipse.ui.IEditorActionDelegate, no caso de contribuições para menus de contexto que pertencem a editores. Em todos os casos, a classe de implementação é carregada o mais tarde possível para evitar carregar a totalidade do conector antes de ser realmente necessário.

Nota: para uma compatibilidade com versões anteriores, pode ser implementado org.eclipse.ui.IActionDelegate para contribuições de objectos.

A extensão do menu de contexto dentro de um componente só é possível quando o componente de destino é publicado num menu para extensão. Isto é recomendado, já que melhora a extensividade do produto. Para o conseguir, cada componente deverá publicar quaisquer menus de contexto que estejam definidos, chamando IWorkbenchPartSite.registerContextMenu. Assim que esta acção estiver concluída, a área de trabalho irá inserir automaticamente quaisquer extensões de acção que existam.

Tem de ser fornecido um ID de menu para cada menu registado. Por uma questão de consistência em todos os componentes, deverá ser adoptada a seguinte estratégia por todos os implementadores dos componentes.

Qualquer menu de contexto que é registado com a área de trabalho deve conter também um ponto de inserção padrão com o ID IWorkbenchActionConstants.MB_ADDITIONS. Os outros conectores irão utilizar este valor como um ponto de referência para a inserção. O ponto de inserção pode ser definido adicionando um GroupMarker ao menu, numa localização apropriada para a inserção.

Um objecto na área de trabalho que seja a selecção num menu de contexto poderá definir um org.eclipse.ui.IActionFilter. Esta é uma estratégia de filtragem que pode executar uma filtragem específico do tipo. A área de trabalho irá recuperar o filtro para a selecção, executando um teste para ver se implementa o IActionFilter. Se falhar, a área de trabalho irá pedir um filtro através do mecanismo IAdaptable.

As etiquetas de acção e de menu podem conter caracteres especiais que codificam as mnemónicas, que foram especificadas utilizando o carácter ('&') antes de um carácter seleccionado no texto traduzido. Uma vez que o carácter e comercial não é permitido nas cadeias XML, utilize uma entidade de carácter &amp;.

Se forem executadas duas ou mais acções num menu por uma extensão única, as acções irão aparecer na ordem inversa à que aparecem enumeradas no ficheiro plugin.xml. Este comportamento é reconhecidamente não intuitivo. No entanto, foi descoberto após a API da Plataforma Eclipse ter sido congelada. A alteração deste comportamento iria provocar danos em todos os conectores que se baseiam nesse comportamento.

Os elementos selection e enablement excluem-se mutuamente. O elemento enablement pode substituir o elemento selection utilizando os subelementos objectClass e objectState. Por exemplo, o seguinte código:

 

<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 visualizações da área de trabalho têm menus de contexto incorporados que já vêm carregados com um número de acções. Os conectores podem efectuar contribuições para esses menus. Se um visualizador reservou espaços para essas contribuições e se estas forem tornadas públicas, os nomes dos espaços podem ser utilizados como caminhos. Caso contrário, as acções e os sub-menus serão adicionados ao final do menu emergente.