Descrição: esse ponto de extensão é utilizado para incluir novas ações aos menus popups de propriedade de outros plug-ins. A contribuição da ação pode ser feita contra um tipo de objeto especificado (objectContribution) ou contra um menu popup especificado. Quando registrado para um tipo de objeto, a contribuição aparecerá em todas as exibições onde objetos de tipo especificado são selecionados. Em contraste, o registro de um menu popup somente aparecerá no menu especificado, não importando a seleção.
Quando uma seleção é heterogênea, a contribuição será aplicada se registrada em um tipo comum de 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 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, a 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 de valores de chave. Os atributos que aplicam-se à seleção são tipos especificados e além do domínio do próprio workbench, de modo que o workbench delegará a filtragem nesse nível na seleção atual.
Marcação da Configuração:
<!ELEMENT objectContribution (filter | menu | action)*
(visibility)?>
<!ATTLIST objectContribution
id
CDATA #REQUIRED
objectClass CDATA #REQUIRED
nameFilter CDATA #IMPLIED
adaptable (true|false)
#IMPLIED
>
Na versão 2.0 de Eclipse, um elemento de visibilidade pode ser utilizado em um objectContribution para definir a visibilidade para a ação. Essa não é uma substituição para o atributo objectClass, que define o destino principal da ação. O elemento de visibilidade é utilizado para aprimorar o destino principal. Para obter mais informações sobre o uso de elemento de visibilidade, consulte actionExpressions.html.<!ELEMENT viewerContribution (menu | action)*>
<!ELEMENT action (selection)* (enablement)?>name - nome do separador que pode mais tarde referir-se ao último token no caminho da ação. Assim sendo, os separadores servem como grupos nomeados cujas ações podem ser incluídas.
Na versão 2.0 de Eclipse, um elemento de ativação pode ser utilizado para definir a ativação para a ação. Para obter mais informações sobre o uso do elemento de ativação, consulte actionExpressions.html.Os critérios de ativação para a extensão de uma ação são inicialmente definidos por enablesFor, seleção e ativação. 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.
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 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 forem contribuídas a um menu ou barra de ferramentas por uma única extensão, as ações aparecerão na ordem inversa de como elas serão listadas no arquivo plugin.xml. Esse procedimento não é reconhecidamente intuitivo. Entretanto, ele foi descoberto após a API da Plataforma Eclipse estava pendente. Alterar o procedimento agora iria interromper cada plug-in que lida com o procedimento existente.
Exemplos:
A seguir um exemplo de um ponto de extensão do menu popup:
<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"
menubarPath="com.xyz.xyzMenu/group1"
icon="icons/runXYZ.gif"
helpContextId="com.xyz.run_action_context"
class="com.xyz.actions.XYZToolActionDelegate"
enablesFor="1">
</action>
</objectContribution>
<viewerContribution
id="com.xyz.C2"
targetID="org.eclipse.ui.views.TaskList">
<action
id="com.xyz.showXYZ"
label="&Show XYZ"
menubarPath="additions"
icon="icons/showXYZ.gif"
helpContextId="com.xyz.show_action_context"
classe="com.xyz.actions.XYZShowActionDelegate">
</action>
</viewerContribution>
</extension>
No exemplo acima, a ação especificada somente ativará uma seleção simples (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 exibidor acima somente aparecerá na exibição Tarefas e não será afetada pela seleção na exibição.
A seguir um exemplo do mecanismo de filtragem. Nesse caso, a ação somente aparecerá para IMarkers que são completos e têm máxima prioridade.
<extension point="org.eclipse.ui.popupMenus">
<objectContribution
id="com.xyz.C1"
objectClass="org.eclipse.core.resources.IMarker">
<filter name="done"
valor="verdadeiro"/>
<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>
Informações de API: o valor do atributo da ação classe deve ser um nome completo de uma classe Java que implementa org.eclipse.ui.IObjectActionDelegate no caso de contribuições de objetos, org.eclipse.ui.IViewActionDelegate para contribuições a visualizadores que pertencem a exibições, ou org.eclipse.ui.IEditorActionDelegate para contribuições para visualizadores que pertençam a 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 necessário.
Nota: para compatibilidade inversa, org.eclipse.ui.IActionDelegate pode ser implementado para contribuições de objeto.
Extensão do menu popup dentro de uma parte somente é possível quando a parte de destino publica um menu para extensão. Isso é imensamente encorajado, uma vez que ele aumenta a extensibilidade do produto. Para realizar isso, cada parte deve publicar qualquer menu popup que for definido ao chamar IWorkbenchPartSite#registerContextMenu. Feito isso, o workbench inserirá automaticamente qualquer das extensões de ação que existir.
Uma identificação de menu deve ser fornecida para cada menu registrado. Para consistência entre as partes, a seguinte estratégia deve ser adotada por todos os implementadores de partes.
Um objeto no workbench que seja a seleção em um menu de contexto pode definir um org.eclipse.ui.IActionFilter. Essa é a estratégia de filtragem que pode executar filtragem de tipo especificado. O workbench recuperará o filtro para a seleção ao testar para ver se ele implementa IActionFilter. Se isso falhar, o workbench perguntará pelo filtro através do mecanismo IAdaptable.
Implementação Fornecida: As exibições do workbench tem menus popup internos que já vêm carregados com um número de 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 poderão ser utilizados como caminhos. De outro modo, as ações e os sub-menus serão incluídos ao final do menu popup.