Menus, Barras de Ferramentas e Acções de Editor

org.eclipse.ui.editorActions

Este ponto de extensão é utilizado para adicionar acções ao menu e à barra de ferramentas de editores registados 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 acções é criado e partilhado por todas as instâncias-objecto do mesmo tipo de editor. Quando invocada, estas acções actuam sobre o editor activo. Este ponto de extensão segue o mesmo padrão. Cada extensão de acção é criada e partilhada por todas as instâncias-objecto do mesmo tipo de editor. A classe de acção tem de implementar org.eclipse.ui.IEditorActionDelegate. O editor activo é transmitido ao delegado invocando IEditorActionDelegate.setActiveEditor.

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 um subelemento.

<!ELEMENT extension (editorContribution+)>

<!ATTLIST extention

point CDATA #REQUIRED

id    CDATA #IMPLIED

name  CDATA #IMPLIED>


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

<!ATTLIST editorContribution

id       CDATA #REQUIRED

targetID CDATA #REQUIRED>

Este elemento é utilizado para definir um editor de acções e/ou menus.



<!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>

Este elemento define uma acção que o utilizador pode invocar na UI.



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



De seguida é apresentado um exemplo de uma extensão de acção de editor:

   

<extension point=

"org.eclipse.ui.editorActions"

>

<editorContribution id=

"com.xyz.xyzContribution"

targetID=

"com.ibm.XMLEditor"

>

<menu id=

"XYZ"

label=

"&amp;Menu XYZ"

>

<separator name=

"group1"

/>

</menu>

<action id=

"com.xyz.runXYZ"

label=

"&amp;Run XYZ Tool"

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 anterior, a acção especificada irá aparecer como um artigo de caixa de verificação no novo menu de nível superior, designado "Menu XYZ", e como botão de comutação na barra de ferramentas. A acção é activada, caso a selecção contenha apenas recursos de ficheiros Java.

De seguida é apresentado outro exemplo de uma extensão de acção de editor:

   

<extension point=

"org.eclipse.ui.editorActions"

>

<editorContribution id=

"com.xyz.xyz2Contribution"

targetID=

"com.ibm.XMLEditor"

>

<menu id=

"XYZ2"

label=

"&amp;Menu XYZ2"

path=

"edit/additions"

>

<separator name=

"group1"

/>

</menu>

<action id=

"com.xyz.runXYZ2"

label=

"&amp;Run XYZ2 Tool"

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 anterior, a acção especificada irá aparecer como um artigo de menu no submenu designado "Menu XYZ2", no menu de nível superior "Editar". A acção é activada se a selecção não contiver quaisquer recursos de ficheiro Java.

O valor do atributo de classe tem de ser um nome totalmente qualificado de uma classe Java que implemente org.eclipse.ui.IEditorActionDelegate. Esta classe é carregada o mais tarde possível, para evitar carregar a totalidade do conector antes que seja realmente necessário. O método setActiveEditor será chamado sempre que um editor do tipo especificado seja activado. Só será criado um conjunto de acções e menus para todas as instâncias-objecto do tipo de editor especificado, independentemente do número de instâncias-objecto do editor que estão abertas na área de trabalho.

Este ponto de extensão pode ser utilizado para contribuir com acções para os menus anteriormente criados pelo editor destino. Além disso, os menus e acções podem ser contribuídos para a janela Área de trabalho. Os identificadores de acções e grupos principais dentro da janela Área de trabalho são definidos em org.eclipse.ui.IWorkbenchActionConstants. Estes devem ser utilizados como um ponto de referência para a adição de novas acções. Os menus de nível superior são criadas utilizando os valores seguintes para o atributo path:

Ao omitir o tributo path, o novo menu será adicionado ao grupo additions da barra de menus.

As acções e os menus adicionados nestes caminhos serão apenas mostrados enquanto o editor associado estiver activo. Quando o editor está fechado, os menus e as acções serão removidos.

Os critérios de activação para uma extensão de acção são inicialmente definidos por enablesFor, e também por selection ou enablement. Contudo, após ser criada uma instância-objecto do delegado da acção, ela poderá controlar o estado de activação da acção directamente dentro do seu método selectionChanged.

As etiquetas de acções e menus podem conter caracteres especiais que codifiquem mnemónicas, utilizando as seguintes regras:

  1. As mnemónicas são especificadas utilizando o carácter de e comercial ('&') antes de um carácter seleccionado no texto traduzido. Dado que e comercial não é permitido em cadeias XML, utilize a entidade de carácter &amp;.
Caso uma única extensão contribua com duas ou mais acções para um menu ou barra de ferramentas, as acções aparecerão segundo uma ordem contrária àquela em que estão 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:

 

<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>

A área de trabalho dispõe de um "Editor de texto predefinido" incorporado. Os plug-ins podem contribuir para este editor ou editores predefinidos facultados por outros plug-ins.