Exibir Menus, Barra de Ferramentas e Ações

org.eclipse.ui.viewActions

Esse ponto de extensão é utilizado para incluir ações no menu de opções e na barra de ferramentas para visualizações registradas por outros plug-ins. Cada exibição tem um menu de opções local normalmente ativado ao clicar no botão triangular no canto superior direito. Outros plug-ins podem contribuir com sub-menus e ações para esse menu. Os plug-ins também podem contribuir com ações para a barra de ferramentas de exibição. Aos proprietários de exibições é dada a primeira chance de ocupar essas áreas. Inclusões opcionais por outros plug-ins são anexadas.

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 (viewContribution+)>

<!ATTLIST extension

point CDATA #REQUIRED

id    CDATA #IMPLIED

name  CDATA #IMPLIED>


<!ELEMENT viewContribution (menu* , action*)>

<!ATTLIST viewContribution

id       CDATA #REQUIRED

targetID CDATA #REQUIRED>

Esse elemento é utilizado para definir um grupo de ações de visualização e/ou menus.



<!ELEMENT action (selection* | enablement?)>

<!ATTLIST action

id            CDATA #REQUIRED

label         CDATA #REQUIRED

menubarPath   CDATA #IMPLIED

toolbarPath   CDATA #IMPLIED

icon          CDATA #IMPLIED

disabledIcon  CDATA #IMPLIED

hoverIcon     CDATA #IMPLIED

tooltip       CDATA #IMPLIED

helpContextId CDATA #IMPLIED

style         (push|radio|toggle) "push"

state         (true | false)

class         CDATA #REQUIRED

enablesFor    CDATA #IMPLIED>

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



<!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 menus 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 a 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.



A seguir, um exemplo de uma extensão de ação de visualização:

   

<extension point=

"org.eclipse.ui.viewActions"

>

<viewContribution id=

"com.xyz.xyzViewC1"

targetID=

"org.eclipse.ui.views.navigator.ResourceNavigator"

>

<menu id=

"com.xyz.xyzMenu"

label=

"XYZ Menu"

path=

"additions"

>

<separator name=

"group1"

/>

</menu>

<action id=

"com.xyz.runXYZ"

label=

"&amp;Executar Ferramenta XYZ"

menubarPath=

"com.xyz.xyzMenu/group1"

toolbarPath=

"Normal/additions"

style=

"toggle"

state=

"true"

icon=

"icons/runXYZ.gif"

tooltip=

"Executar Ferramenta XYZ"

helpContextId=

"com.xyz.run_action_context"

class=

"com.xyz.actions.RunXYZ"

>

<selection class=

"org.eclipse.core.resources.IFile"

name=

"*.java"

/>

</action>

</viewContribution>

</extension>

No exemplo acima, a ação especificada somente ativará uma seleção simples (atributo enablesFor).Além disso, o objeto na seleção deve ser um recurso de arquivo Java.

A seguir é apresentado outro exemplo de uma extensão de ação de exibição:

   

<extension point=

"org.eclipse.ui.viewActions"

>

<viewContribution id=

"com.xyz.xyzViewC1"

targetID=

"org.eclipse.ui.views.navigator.ResourceNavigator"

>

<menu id=

"com.xyz.xyzMenu"

label=

"XYZ Menu"

path=

"additions"

>

<separator name=

"group1"

/>

</menu>

<action id=

"com.xyz.runXYZ2"

label=

"&amp;Executar Ferramenta XYZ2"

menubarPath=

"com.xyz.xyzMenu/group1"

style=

"push"

icon=

"icons/runXYZ2.gif"

tooltip=

"Executar Ferramenta XYZ2"

helpContextId=

"com.xyz.run_action_context2"

class=

"com.xyz.actions.RunXYZ2"

>

<enablement>

<and>

<objectClass name=

"org.eclipse.core.resources.IFile"

/>

<not>

<objectState name=

"extension"

value=

"java"

/>

</not>

</and>

</enablement>

</action>

</viewContribution>

</extension>

No exemplo acima, a ação especificada aparecerá como um item de menu. A ação será ativada se a seleção não contiver recursos de arquivo Java.

O valor do atributo class deve ser um nome completo de uma classe Java que implementa org.eclipse.ui.IViewActionDelegate. Essa classe é carregada o mais tarde possível para evitar o carregamento de todo o plug-in antes que isso seja realmente necessário.

A interface org.eclipse.ui.IViewActionDelegate estende org.eclipse.ui.IActionDelegate e inclui um método adicional que permite ao delegado inicializar com uma instância de exibição com a qual está contribuindo.

Esse ponto de extensão pode ser utilizado para contribuir com ações nos menus criados anteriormente pela exibição de destino. A omissão do atributo path do menu resultará na inclusão do novo menu ou ação no final do menu de opções.

Os critérios de ativação para uma extensão de ação é inicialmente definida por enablesFor e também por selection ou 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.

Os rótulos das ações e de menus podem conter caracteres especiais que codificam mnemônicos utilizando as seguintes regras:

  1. Mnemônicos são especificados utilizando o caracter e comercial ('&') antes de um caracter 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 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 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>

Cada visualização normalmente vem com vários itens padrão no menu de opções e na barra de ferramentas local. As adições de outros plug-ins serão anexadas ao complemento padrão.