Menus Editor, Barra de Ferramentas e Ações

Identificador: org.eclipse.ui.editorActions

Descrição: Este ponto de extensão é utilizado para incluir ações ao menu e à 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 visibilidade de uma ação pode ser definida 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 de uma ação.

A sintaxe dos elementos enablement e visibility é a mesma. Ambos contêm apenas um subelemento de expressão booleana. No caso mais simples, esse subelemento será um elemento objectClass, objectState, pluginState ou systemProperty. No caso mais complexo, os elementos and, or e not poderão ser combinados para formar uma expressão booleana. Os elementos and e or devem conter 2 subelementos. O elemento not deve conter apenas 1 subelemento.

Marcação da Configuração:

   <!ELEMENT extension (editorContribution+)>

   <!ATTLIST extension
     point CDATA #REQUIRED
     id    CDATA #IMPLIED
     name  CDATA #IMPLIED
   >

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

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

   <!ATTLIST editorContribution
      id       CDATA #REQUIRED
     targetID CDATA #REQUIRED
   >

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

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

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

   <!ELEMENT menu (separator+ , groupMarker*)>

   Este elemento é utilizado para definir um novo menu.

   <!ATTLIST menu
      id    CDATA #REQUIRED
      label CDATA #REQUIRED
     path  CDATA #IMPLIED
   >

   <!ELEMENT separator EMPTY>

   Este elemento é utilizado para criar um separador de menus no novo menu.

   <!ATTLIST separator
     name CDATA #REQUIRED
   >

   <!ELEMENT groupMarker EMPTY>

   Este elemento é utilizado para criar um grupo nomeado no novo menu. Ele não tem nenhuma representação visual no novo menu, diferente do elemento separator.

   <!ATTLIST groupMarker
     name CDATA #REQUIRED
   >

   <!ELEMENT selection EMPTY>

   Este elemento é utilizado para ajudá-lo a determinar a ativação da ação com base na seleção atual. Será ignorado se o elemento enablement estiver especificado.

   <!ATTLIST selection
      class CDATA #REQUIRED
     name  CDATA #IMPLIED
   >

   <!ELEMENT enablement (and | or | not | objectClass | objectState | pluginState | systemProperty)>

   Este elemento é utilizado para definir a ativação da ação.

   <!ELEMENT visibility (and | or | not | objectClass | objectState | pluginState | systemProperty)>

   Este elemento é utilizado para definir a visibilidade da ação.

   <!ELEMENT and (and | or | not | objectClass | objectState | pluginState | systemProperty)>

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

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

   Este elemento representa uma operação booleana NOT como resultado da avaliação de expressões de subelementos.

   <!ELEMENT objectClass EMPTY>

   Este 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 a interface especificada, a expressão será avaliada como true.

   <!ATTLIST objectClass
     name CDATA #REQUIRED
   >

   <!ELEMENT objectState EMPTY>

   Este elemento é utilizado para avaliar o estado de atributo de cada objeto na seleção atual. Se cada objeto na seleção tiver o estado de atributo especificado, a expressão será avaliada como true. Para avaliar esse tipo de expressão, cada objeto na seleção deve implementar ou adaptar-se à interface org.eclipse.ui.IActionFilter.

   <!ATTLIST objectState
     name  CDATA #REQUIRED
     value CDATA #REQUIRED
   >

   <!ELEMENT pluginState EMPTY>

   Este elemento é utilizado para avaliar o estado de um plug-in. O estado do plug-in pode ser um dos seguintes: installed ou activated.

   <!ATTLIST pluginState
      id    CDATA #REQUIRED
     value (installed|activated) "installed"
   >

   <!ELEMENT systemProperty EMPTY>

   Este elemento é utilizado para avaliar o estado de algumas propriedades do sistema. O valor da propriedade é recuperado de java.lang.System.

   <!ATTLIST systemProperty
     name  CDATA #REQUIRED
     value CDATA #REQUIRED
   >
Exemplos: A seguir, um exemplo de extensão da ação de um 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;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 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;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 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 nenhum recurso de arquivo Java.

Informações de API: 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 Workbench.

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 Workbench. Os identificadores de ações e grupos principais na janela do Workbench 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.

O critério de ativação da extensão de uma ação é inicialmente definido por enablesFor e também por selection ou enablement. Entretanto, depois que a ação delegada é instanciada, ela pode controlar o estado de ativação da ação diretamente dentro do seu método selectionChanged.

A ação e os rótulos 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. Este comportamento é reconhecidamente não-intuitivo. Entretanto, ele foi descoberto depois que a API da Plataforma Eclipse foi congelada. Alterar o comportamento agora interromperia todos os plug-ins que lidam com o comportamento existente.

Os elementos selection e enablement são mutuamente exclusivos. O elemento enablement pode substituir o elemento selection utilizando os subelementos objectClass e objectState. O exemplo:

 <selection
  class="org.eclipse.core.resources.IFile"
  name="*.java">
 </selection>
pode ser expressado utilizando:
 <enablement>
  <and>
   <objectClass name="org.eclipse.core.resources.IFile"/>
   <objectState name="extension" value="java"/>
  </and>
 </enablement>

Implementação Fornecida: O Workbench fornece um "Editor de Texto Padrão" integrado. Os Plug-ins podem contribuir dentro desse editor padrão ou editores fornecidos por outros plug-ins.

Copyright (c) 2000, 2003 IBM Corporation e outros. Todos os direitos reservados. Este programa e os materiais que o acompanham são disponibilizados sob os termos da Common Public License v1.0 que acompanha esta distribuição e estão disponíveis no endereço http://www.eclipse.org/legal/cpl-v10.html