Menus Editor, Barra de Ferramentas e Ações

org.eclipse.ui.editorActions

Esse ponto de extensão é utilizado para incluir ações no menu e na barra de ferramentas para editores registrados por outros plug-ins.

O conjunto de contribuição inicial de um editor é definido por outro ponto de extensão (org.eclipse.ui.editors). Um conjunto de ações é criado e compartilhado por todas as instâncias do mesmo tipo de editor. Quando chamado, essas ações agem de acordo com o editor ativo. Esse ponto de extensão segue o mesmo padrão. A extensão de cada ação é criada e compartilhada por todas as instâncias do mesmo tipo de editor. A classe da ação é requerida para implementar org.eclipse.ui.IEditorActionDelegate. O editor ativo é transmitido ao representante chamando IEditorActionDelegate.setActiveEditor.

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

<!ATTLIST extension

point CDATA #REQUIRED

id    CDATA #IMPLIED

name  CDATA #IMPLIED>


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

<!ATTLIST editorContribution

id       CDATA #REQUIRED

targetID CDATA #REQUIRED>

Esse elemento é utilizado para definir um grupo de ações e/ou menus do editor.



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

<!ATTLIST action

id            CDATA #REQUIRED

label         CDATA #REQUIRED

accelerator   CDATA #IMPLIED

definitionId  CDATA #IMPLIED

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

actionID      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 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 ajudá-lo 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 de 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 alguma propriedade do sistema. O valor da propriedade é recuperado de java.lang.System.



A seguir um exemplo de uma extensão da ação do editor:

   

<extension point=

"org.eclipse.ui.editorActions"

>

<editorContribution id=

"com.xyz.xyzContribution"

targetID=

"com.ibm.XMLEditor"

>

<menu id=

"XYZ"

label=

"&amp;XYZ Menu"

>

<separator name=

"group1"

/>

</menu>

<action id=

"com.xyz.runXYZ"

label=

"&amp;Executar Ferramenta XYZ"

menubarPath=

"XYZ/group1"

toolbarPath=

"Normal/additions"

style=

"toggle"

state=

"true"

icon=

"icons/runXYZ.gif"

tooltip=

"Run XYZ Tool"

helpContextId=

"com.xyz.run_action_context"

class=

"com.xyz.actions.RunXYZ"

>

<selection class=

"org.eclipse.core.resources.IFile"

name=

"*.java"

/>

</action>

</editorContribution>

</extension>

No exemplo acima, a ação especificada aparecerá como um item da caixa de opção no novo menu de nível superior nomeado "XYZ Menu" e como um botão de comutação na barra de ferramentas. A ação será ativada se a seleção contiver apenas recursos de arquivo Java.

A seguir, outro exemplo de extensão da ação de um editor:

   

<extension point=

"org.eclipse.ui.editorActions"

>

<editorContribution id=

"com.xyz.xyz2Contribution"

targetID=

"com.ibm.XMLEditor"

>

<menu id=

"XYZ2"

label=

"&amp;XYZ2 Menu"

path=

"edit/additions"

>

<separator name=

"group1"

/>

</menu>

<action id=

"com.xyz.runXYZ2"

label=

"&amp;Executar Ferramenta XYZ2"

menubarPath=

"edit/XYZ2/group1"

style=

"push"

icon=

"icons/runXYZ2.gif"

tooltip=

"Run XYZ2 Tool"

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>

</editorContribution>

</extension>

No exemplo acima, a ação especificada aparecerá como um item de menu no submenu chamado "XYZ2 Menu", no menu "Edit" de nível superior. 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.IEditorActionDelegate. Essa classe é carregada o mais tarde possível para evitar o carregamento de todo o plug-in antes que isso seja realmente necessário. O método setActiveEditor será chamado toda vez que um editor de um tipo especificado for ativado. Somente um conjunto de ações e menus será criado para todas as instâncias do tipo de editor especificado, independente do número de instâncias do editor atualmente abertas no Ambiente de Trabalho.

Esse ponto de extensão pode ser utilizado para contribuir com ações dentro de menus previamente criados pelo editor de destino. Além disso, os menus e as ações podem contribuir com a janela do Ambiente de Trabalho. Os identificadores de ações e grupos principais na janela do Ambiente de Trabalho são definidos em org.eclipse.ui.IWorkbenchActionConstants. Eles devem ser utilizados como um ponto de referência para a inclusão de novas ações. Menus de nível superior são criados utilizando os seguintes valores para o atributo path:

A omissão do atributo path resultará na inclusão de um novo menu no grupo de barra de menus additions.

As ações e os menus incluídos dentro desses caminhos somente serão mostrados enquanto o editor associado estiver ativo. Quando o editor for fechado, os menus e as ações serão removidos.

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>

O Ambiente de Trabalho fornece um "Editor de Texto Padrão" interno. Os Plug-ins podem contribuir dentro desse editor padrão ou editores fornecidos por outros plug-ins.