Menus Pop-up

Identificador: org.eclipse.ui.popupMenus

Descrição: Esse ponto de extensão é utilizado para adicionar novas ações a menus de contexto pertencentes a outros plug-ins. A contribuição da ação pode ser feita sobre um tipo de objeto especificado (objectContribution) ou sobre um menu de contexto específico de uma parte de exibição ou de editor (viewerContribution). Ao utilizar objectContribution, a contribuição aparecerá em todos os menus de contexto da parte de exibição ou de editor em que objetos do tipo especificado são selecionados. Em contraste, utilizando viewerContribution, a contribuição aparecerá somente no menu de contexto da parte de exibição ou do editor especificada, independentemente da seleção.

Quando uma seleção é heterogênea, a contribuição será aplicada se registrada em um tipo comum de seleção, se possível. Se uma correspondência não for possível, a correspondência em relação a super classes e super interfaces será tentada.

A seleção pode ser futuramente limitada por meio da utilização de um filtro de nome. Se utilizado, todos os objetos na seleção devem corresponder ao filtro a fim de se aplicarem à contribuição.

Ações individuais em uma contribuição de objeto podem utilizar o atributo enablesFor para especificar se o mesmo deve se aplicar somente para tipo de seleção simples, múltipla ou para qualquer outro tipo de seleção.

Se esses mecanismos de filtragem forem inadequados, uma contribuição de ação poderá utilizar o mecanismo filtro. Nesse caso os atributos do objeto de destino são descritos em uma série de pares nome-valor. Os atributos que aplicam-se à seleção são específicos dos tipos e além do domínio do próprio workbench, de modo que o workbench delegará a filtragem nesse nível na seleção atual.

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 (objectContribution , viewerContribution)>

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

   <!ELEMENT objectContribution (filter* , visibility? , menu* , action*)>

   Esse elemento é utilizado para definir um grupo de ações e/ou menus para quaisquer menus de contexto do visualizador para os quais os objetos do tipo especificado são selecionados.

   <!ATTLIST objectContribution
     id          CDATA #REQUIRED
     objectClass CDATA #REQUIRED
     nameFilter  CDATA #IMPLIED
     adaptable   (true | false) "false"
   >

   <!ELEMENT viewerContribution (visibility? , menu* , action*)>

   Esse elemento é utilizado para definir um grupo de ações e/ou menus para um menu de contexto da parte de exibição ou editor específicos.

   <!ATTLIST viewerContribution
     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
     icon             CDATA #IMPLIED
     helpContextId    CDATA #IMPLIED
     style            (push|radio|toggle)
     state            (true | false)
     class            CDATA #REQUIRED
     enablesFor       CDATA #IMPLIED
     overrideActionId CDATA #IMPLIED
     tooltip          CDATA #IMPLIED
   >

   <!ELEMENT filter EMPTY>

   Esse elemento é utilizado para avaliar o estado do atributo de cada objeto na seleção atual. Uma correspondência ocorrerá apenas se cada objeto na seleção tiver o estado de atributo especificado. Cada objeto na seleção deve implementar, ou se adaptar a, org.eclipse.ui.IActionFilter.

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

   <!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 um ponto de extensão de menu pop-up:

   <extension point="org.eclipse.ui.popupMenus"> 
      <objectContribution 
         id="com.xyz.C1" 
         objectClass="org.eclipse.core.resources.IFile" 
         nameFilter="*.java"> 
         <menu
            id="com.xyz.xyzMenu" 
            path="additions" 
            label="Ferramentas Java do &amp;XYZ">
            <separator name="group1"/> 
         </menu> 
         <action
            id="com.xyz.runXYZ" 
            label="&amp;Executar Ferramenta XYZ"
            style="push"
            menubarPath="com.xyz.xyzMenu/group1" 
            icon="icons/runXYZ.gif" 
            helpContextId="com.xyz.run_action_context" 
            class="com.xyz.actions.XYZToolActionDelegate" 
            enablesFor="1"> 
         </action> 
      </objectContribution> 
      <viewerContribution 
         id="com.xyz.C2" 
         targetID="org.eclipse.ui.views.TaskList"> 
         <action
            id="com.xyz.showXYZ" 
            label="&amp;Mostrar XYZ"
            style="toggle"
            state="true"
            menubarPath="additions" 
            icon="icons/showXYZ.gif" 
            helpContextId="com.xyz.show_action_context" 
            class="com.xyz.actions.XYZShowActionDelegate"> 
         </action> 
      </viewerContribution> 
   </extension> 

No exemplo acima, a ação de contribuição de objeto especificada somente irá ativar para uma única seleção (atributo enablesFor). Além disso, cada objeto na seleção deve implementar a interface especificada (IFile) e deve ser um arquivo tipo Java.Essa ação será incluída dentro de um sub-menu previamente criado. Essa contribuição será efetiva em qualquer exibição que tenha a seleção solicitada.

Ao contrário, a contribuição do visualizador acima somente aparecerá no menu de contexto da exibição Tarefas e não será afetada pela seleção na exibição.

A seguir encontra-se um exemplo do mecanismo de filtro. Nesse caso, a ação somente aparecerá para IMarkers que são completos e têm alta prioridade.

   <extension point="org.eclipse.ui.popupMenus"> 
      <objectContribution 
         id="com.xyz.C3" 
         objectClass="org.eclipse.core.resources.IMarker"> 
         <filter name="done" value="true"/> 
         <filter name="priority" value="2"/> 
         <action
            id="com.xyz.runXYZ" 
            label="Ferramenta de Ação Concluída de Alta Prioridade"
            icon="icons/runXYZ.gif" 
            class="com.xyz.actions.MarkerActionDelegate"> 
         </action> 
      </objectContribution> 
   </extension> 

A seguir encontra-se outro exemplo da utilização do elemento visibility:

   <extension point="org.eclipse.ui.popupMenus"> 
      <viewerContribution 
         id="com.xyz.C4" 
         targetID="org.eclipse.ui.views.TaskList">
         <visibility>
            <and>
               <pluginState id="com.xyz" value="activated"/>
               <systemProperty name="ADVANCED_MODE" value="true"/>
            </and>
         </visibility>
         <action
            id="com.xyz.showXYZ" 
            label="&amp;Mostrar XYZ"
            style="push"
            menubarPath="additions" 
            icon="icons/showXYZ.gif" 
            helpContextId="com.xyz.show_action_context" 
            class="com.xyz.actions.XYZShowActionDelegate"> 
         </action> 
      </viewerContribution> 
   </extension> 

No exemplo acima, a ação especificada aparecerá como um item de menu no menu de contexto da exibição Tarefa, mas somente se o plug-in "com.xyz" estiver ativo e a propriedade do sistema especificado for definida como true.

Informações de API: O valor da classe do atributo de ação deve ser um nome de classe completo de uma classe Java que implemente org.eclipse.ui.IObjectActionDelegate no caso de contribuições do objeto, org.eclipse.ui.IViewActionDelegate para contribuições de menus de contexto que pertencem a exibições ou org.eclipse.ui.IEditorActionDelegate para contribuições de menus de contexto que pertencem a editores. Em todos os casos, a classe de implementação é carregada o mais tarde possível para evitar o carregamento de todo o plug-in antes que isso seja realmente necessário.

Nota: Para compatibilidade inversa, org.eclipse.ui.IActionDelegate pode ser implementado para contribuições de objeto.

A extensão de menu de contexto dentro de uma parte será possível apenas quando a parte de destino publicar um menu para extensão. Isso é altamente encorajado, pois aprimora a extensibilidade do produto. Para realizar isso, cada parte deve publicar quaisquer menus de contexto que são definidos chamando IWorkbenchPartSite.registerContextMenu. Após isso ser feito, o workbench irá inserir automaticamente quaisquer extensões de ações existentes.

Um ID de menu deve ser fornecido para cada menu registrado. Para consistência entre as partes, a seguinte estratégia deve ser adotada por todos os implementadores de partes.

Qualquer menu de contexto que esteja registrado no workbench também deve conter um ponto de inserção padrão com ID IWorkbenchActionConstants.MB_ADDITIONS. Outros plug-ins utilizarão esse valor como um ponto de referência para inserção. O ponto de inserção pode ser definido pela adição de um GroupMarker ao menu em uma localização apropriada para inserção.

Um objeto no workbench que é a seleção em um menu de contexto pode definir um org.eclipse.ui.IActionFilter. Essa é uma estratégia de filtragem que pode executar filtragem específica de tipos. O workbench recuperará o filtro para a seleção testando se ela implementa IActionFilter. Se isso falhar, o workbench solicitará um filtro por meio do mecanismo IAdaptable.

Os rótulos de ação e de menu podem conter caracteres especiais que codificam mnemônicos os quais são especificados utilizando o caracter e comercial ('&') em frente de um caractere selecionado 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 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: As exibições do workbench possuem menus de contexto embutidos que já vêm carregados com várias ações. Os plug-ins podem contribuir para esses menus. Se um visualizador tiver reservado slots para essas contribuições e eles se tornarem públicos, os nomes dos slots podem ser utilizados como caminhos. De outro modo, as ações e os sub-menus serão incluídos ao final do menu pop-up.

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