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.
push | - como artigo de menu ou artigo de barra de ferramentas habitual. | |
radio | - como artigo de menu ou de barra de ferramentas de estilo de botão de opção. As acções com o estilo de botão de opção dentro do mesmo grupo do menu ou da barra de ferramentas agem como um conjunto de botões de selecção. O valor inicial é especificado pelo atributo state. | |
toggle | - como um artigo de menu ou da barra de ferramentas do tipo marca de selecção. O valor inicial é especificado pelo atributo state. | |
pulldown | - como um artigo do menu do estilo em cascata. |
! | - 0 artigos seleccionados | |
? | - 0 ou 1 artigos seleccionados | |
+ | - 1 ou mais artigos seleccionados | |
multiple, 2+ | - 2 ou mais artigos seleccionados | |
n | - um número preciso de artigos seleccionados. Por exemplo: enablesFor=" 4" activa a acção apenas quando são seleccionados 4 artigos | |
* | - qualquer número de artigos seleccionados |
Os critérios de activação para uma extensão de acção são inicialmente definidos por enablesFor, selection e enablement. No entanto, assim que o delegado de acção é dividido em instâncias, poderá controlar o estado de activação da acção directamente dentro do respectivo método selectionChanged.
<!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.
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.<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=
"&XYZ Java Tools"
>
<separator name=
"group1"
/>
</menu>
<action id=
"com.xyz.runXYZ"
label=
"&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=
"&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>
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.
A seguir encontra um outro exemplo da utilização do elemento de visibilidade:<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>
<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=
"&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.
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 &.
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:
pode ser expresso utilizando:<selection class=
"org.eclipse.core.resources.IFile"
name=
"*.java"
>
</selection>
<enablement>
<and>
<objectClass name=
"org.eclipse.core.resources.IFile"
/>
<objectState name=
"extension"
value=
"java"
/>
</and>
</enablement>
Copyright (c) 2000, 2005 IBM Corporation e outros.
Todos os direitos reservados. Este programa e os materiais que o acompanham estão disponíveis
sob os termos da Eclipse Public License v1.0 que acompanha
esta distribuição e está disponível em http://www.eclipse.org/legal/epl-v10.html