Exibir Menus, Barra de Ferramentas e Ações

Identificador: org.eclipse.ui.viewActions

Descrição: Esse ponto de extensão é utilizado para adicionar ações ao menu de opções e à barra de ferramentas para exibiçõ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.

Marcação da Configuração:

   <!ELEMENT extension (viewContribution+)>

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

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

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

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

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

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

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

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

   Esse elemento é utilizado para definir um novo menu.

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

   <!ELEMENT separator EMPTY>

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

   <!ATTLIST separator
     name CDATA #REQUIRED
   >

   <!ELEMENT groupMarker EMPTY>

   Esse elemento é utilizado para criar um grupo nomeado no novo menu. Não há representação visual no novo menu, diferentemente do elemento separator.

   <!ATTLIST groupMarker
     name CDATA #REQUIRED
   >

   <!ELEMENT selection EMPTY>

   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.

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

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

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

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

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

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

   Esse elemento representa uma operação booleana AND sobre o resultado da avaliação de suas expressões de dois sub-elementos.

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

   Esse elemento representa uma operação booleana OR sobre o resultado da avaliação de suas expressões de dois sub-elementos.

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

   Esse elemento representa uma operação booleana NOT sobre o resultado da avaliação de suas expressões de sub-elementos.

   <!ELEMENT objectClass EMPTY>

   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.

   <!ATTLIST objectClass
     name CDATA #REQUIRED
   >

   <!ELEMENT objectState EMPTY>

   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.

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

   <!ELEMENT pluginState EMPTY>

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

   Esse elemento é utilizado para avaliar o estado de alguma propriedade do sistema. O valor da propriedade é recuperado de java.lang.System.

   <!ATTLIST systemProperty
     name  CDATA #REQUIRED
     value CDATA #REQUIRED
   >
Exemplos: A seguir é apresentado um 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="Menu XYZ"
            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="Menu XYZ"
            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> 
      </editorContribution> 
   </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.

Informações de API: o valor do atributo de classe 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>

Implementação Fornecida: cada visualização normalmente vem com um número de 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.

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 Licença Pública Comum v1.0 que acompanha essa distribuição, e está disponível em http://www.eclipse.org/legal/cpl-v10.html