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.
push | - como um item de menu ou de ferramenta normal. | |
radio | - como um item de menu ou de ferramenta no estilo de opções. As ações com o estilo de opções no mesmo grupo de menu ou barra de ferramentas se comportam como um conjunto de opções. O valor inicial é especificado pelo atributo state. | |
toggle | - como um item de menu ou de ferramenta de comutação no estilo de marcação. O valor inicial é especificado pelo atributo state. | |
pulldown | - como um item de menu com estilo em cascata. |
! | - 0 itens selecionados | |
? | - 0 ou 1 item selecionado | |
+ | - 1 ou mais itens selecionados | |
vários, 2+ | - 2 ou mais itens selecionados | |
n | - um número preciso de itens selecionado. Por exemplo: enablesFor=" 4" ativa a ação apenas quando 4 itens forem selecionados | |
* | - qualquer número de itens selecionados |
Os critérios de ativação para a extensão de uma ação são inicialmente definidos por enablesFor, selection e enablement. Entretanto, uma vez que a ação delegada tenha sido instanciada, ela pode controlar o estado de ativação da ação diretamente dentro do seu método selectionChanged.
<!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.
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.<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 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.
A seguir encontra-se outro exemplo da utilização do elemento visibility:<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 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.
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 &.
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:
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>
Direitos Autorais (c) 2000, 2005 IBM Corporation e outros.
Todos os direitos reservados. Este programa e os materiais que o acompanham são disponibilizados
sob os termos da Eclipse Public License v1.0 que acompanha esta
distribuição e estão disponíveis no endereço http://www.eclipse.org/legal/epl-v10.html