Conjuntos de Ação

Identificador: org.eclipse.ui.actionSets

Descrição: Este ponto de extensão é utilizado para incluir menus, itens de menu e botões da barra de ferramentas em áreas comuns na janela do Workbench. Essas contribuições são conhecidas coletivamente como um conjunto de ações e são exibidas dentro da janela do Workbench pelo usuário que está personalizando uma perspectiva.

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

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

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

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

   <!ATTLIST actionSet
      id          CDATA #REQUIRED
      label       CDATA #REQUIRED
     visible     (true | false)
     description CDATA #IMPLIED
   >

   <!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|pulldown) "push"
     state            (true | false)
     pulldown         (true | false)
     class            CDATA #IMPLIED
     retarget         (true | false)
     allowLabelUpdate (true | false)
     enablesFor       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 um conjunto de ações (observe que os subelementos e que os atributos de modo são utilizados):

    <extension point = "org.eclipse.ui.actionSets"> 
        <actionSet
            id="com.xyz.actionSet" 
            label="My Actions"> 
            <menu
               id="com.xyz.xyzMenu" 
               label="XYZ Menu"
               path="additions"> 
               <separator name="group1"/>
               <separator name="option1"/>
            </menu>
            
            <action
               id="com.xyz.runXYZ" 
               label="&amp;Run XYZ Tool"
               style="toggle"
               state="false"
               menubarPath="com.xyz.xyzMenu/group1" 
               icon="icons/runXYZ.gif" 
               tooltip="Run XYZ Tool" 
               helpContextId="com.xyz.run_action_context" 
               class="com.xyz.actions.RunXYZ" 
enablesFor="1">
               <selection class="org.eclipse.core.resources.IFile" name="*.java"/> 
            </action>
            <action 
               id="com.xyz.runABC"
               label="&amp;Run ABC Tool"
               style="push"
               menubarPath="com.xyz.xyzMenu/group1"
               toolbarPath="Normal/XYZ"
               icon="icons/runABC.gif"
               tooltip="Run ABC Tool"
               helpContextId="com.xyz.run_abc_action_context"
               retarget="true"
               allowLabelUpdate="true">
               <enablement>
                  <and>
                     <objectClass name="org.eclipse.core.resources.IFile"/>
                     <not>
                        <objectState name="extension" value="java"/>
                     </not>
                  </and>
               </enablement>
            </action>             

            <action 
               id="com.xyz.runDEF"
               label="&amp;Run DEF Tool"
               style="radio"
               state="true"
               menubarPath="com.xyz.xyzMenu/option1"
               icon="icons/runDEF.gif"
               tooltip="Run DEF Tool"
               class="com.xyz.actions.RunDEF" 
               helpContextId="com.xyz.run_def_action_context">
            </action>             
            <action 
               id="com.xyz.runGHI"
               label="&amp;Run GHI Tool"
               style="radio"
               state="false"
               menubarPath="com.xyz.xyzMenu/option1"
               icon="icons/runGHI.gif"
               tooltip="Run GHI Tool"
               class="com.xyz.actions.RunGHI" 
               helpContextId="com.xyz.run_ghi_action_context">
            </action>             
            <action 
               id="com.xyz.runJKL"
               label="&amp;Run JKL Tool"
               style="radio"
               state="false"
               menubarPath="com.xyz.xyzMenu/option1"
               icon="icons/runJKL.gif"
               tooltip="Run JKL Tool"
               class="com.xyz.actions.RunJKL" 
               helpContextId="com.xyz.run_jkl_action_context">
            </action>             
        </actionSet> 
    </extension> 

No exemplo acima, o conjunto de ações especificado, chamado "My Actions", não está inicialmente visível dentro de cada perspectiva, pois o atributo visible não está especificado.

A ação XYZ aparecerá como um item de menu da caixa de opções, inicialmente não marcada. Ela será ativada apenas se a contagem de seleção for 1 e se a seleção contiver um recurso do arquivo Java.

A ação ABC aparecerá no menu e na barra de ferramentas. Ela será ativada apenas se a seleção não contiver nenhum recurso do arquivo Java. Observe também que ela é uma ação para destinar novamente rótulos e que, portanto, não fornece um atributo class.

As ações DEF, GHI e JKL aparecem como itens de menu do botão de opções. Elas estão ativadas o tempo todo, independente do estado de seleção atual.

Informações de API: O valor do atributo class deve ser o nome completo de uma classe que implementa org.eclipse.ui.IWorkbenchWindowActionDelegate ou org.eclipse.ui.IWorkbenchWindowPulldownDelegate. Esse último deve ser implementado quando o atributo style tiver o valor pulldown. Esta classe é a rotina de tratamento responsável pela execução da ação. Se o atributo retarget for true, ele será ignorado e não deverá ser fornecido.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 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.

É importante observar que o workbench não gera menus em favor de um plug-in. Os caminhos de menus devem fazer referência aos menus já existentes.

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: Os plug-ins podem utilizar este ponto de extensão para incluir novos menus de nível superior. Os plug-ins também podem definir grupos nomeados que permitam a outros plug-ins contribuir com suas ações dentro deles.

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.

Os grupos padrão em uma janela do Workbench são definidos na interface IWorkbenchActionConstants. Essas constantes podem ser utilizadas no código para contribuição dinâmica. Os valores também podem ser copiados para um arquivo XML para uma melhor integração granular com os menus do workbench e barra de ferramentas existentes.

Vários itens de menus e de barra de ferramentas na janela do Workbench são definidos em forma de algoritmos. Nesses casos, um mecanismo separado deve ser utilizado para estender a janela. Por exemplo, a inclusão de uma nova exibição do workbench resulta em um novo item de menu que aparece no menu Perspectiva. As extensões Importar, Exportar e Novos Assistentes também são incluídas automaticamente à janela.

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