Menus Popup

Identificador: org.eclipse.ui.popupMenus

Descrição: esse ponto de extensão é utilizado para incluir novas ações aos menus popups de propriedade de outros plug-ins.  A contribuição da ação pode ser feita contra um tipo de objeto especificado (objectContribution) ou contra um menu popup especificado. Quando registrado para um tipo de objeto, a contribuição aparecerá em todas as exibições onde objetos de tipo especificado são selecionados. Em contraste, o registro de um menu popup somente aparecerá no menu especificado, não importando a 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 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, a 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 de valores de chave.   Os atributos que aplicam-se à seleção são tipos especificados 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.

Marcação da Configuração:

   <!ELEMENT objectContribution (filter | menu | action)*>
   <!ATTLIST objectContribution
      id          CDATA #REQUIRED
      objectClass CDATA #REQUIRED
      nameFilter  CDATA #IMPLIED
   >

   <!ELEMENT viewerContribution (menu | action)*>
   <!ATTLIST viewerContribution
      id        CDATA #REQUIRED
      targetID  CDATA #REQUIRED
   >    <!ELEMENT filter EMPTY>
   <!ATTLIST filter
      name       CDATA #REQUIRED
      value      CDATA #REQUIRED
   >    <!ELEMENT menu (separator)+>
   <!ATTLIST menu
      id         CDATA #REQUIRED
      label      CDATA #REQUIRED
      path       CDATA #IMPLIED
   >    <!ELEMENT separator EMPTY>
   <!ATTLIST separator
      name       CDATA #REQUIRED
   >
  • name - nome do separador que pode mais tarde referir-se ao último token no caminho da ação. Assim sendo, os separadores servem como grupos nomeados cujas ações podem ser incluídas.
  •    <!ELEMENT action EMPTY>
       <!ATTLIST action
          id                NMTOKEN #REQUIRED
          label             CDATA #REQUIRED
          menubarPath       CDATA #IMPLIED
          icon              CDATA #IMPLIED
          helpContextId     CDATA #IMPLIED
          state             (true | false) #IMPLIED
          class             CDATA #REQUIRED
          enablesFor        CDATA #IMPLIED
       > Os critérios de ativação para a extensão de uma ação são inicialmente definidos por enablesFor e seleção.  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.

    A ação e as etiquetas de menu podem conter caracteres especiais que codificam mnemônicos e aceleradores 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;.
    2. Aceleradores opcionais são especificados ao final da cadeia de nome, utilizando-se o '@' seguido por uma série de modificadores e o caracter do acelerador final (por exemplo, &amp;Save@Ctrl+S). Os aceleradores com mais de um modificador são obtidos por modificadores de encadeamento, utilizando o sinal '+' como um delimitador (como em @Ctrl+Shift+S).
    Exemplos:

    A seguir um exemplo de um ponto de extensão do menu popup:

       <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="&amp;XYZ Java Tools">
                <separator name="group1"/>
             </menu>
             <action id="com.xyz.runXYZ"
                  label="&amp;Run XYZ Tool"
                  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;Show XYZ"
                       menubarPath="additions"
                       icon="icons/showXYZ.gif"
                       helpContextId="com.xyz.show_action_context"
                       classe="com.xyz.actions.XYZShowActionDelegate">
               </action>
            </viewerContribution>
         </extension>

    No exemplo acima, a ação 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 exibidor acima somente aparecerá na exibição Tarefas e não será afetada pela seleção na exibição.

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

       <extension point="org.eclipse.ui.popupMenus">
          <objectContribution
             id="com.xyz.C1"
             objectClass="org.eclipse.core.resources.IMarker">
             <filter name="done" valor="verdadeiro"/>
             <filter name="priority" value="2"/>
             <action id="com.xyz.runXYZ"
                  label="High Priority Completed Action Tool"
                  icon="icons/runXYZ.gif"
                  class="com.xyz.actions.MarkerActionDelegate">
              </action>
            </objectContribution>
         </extension>

    Informações de API:  o valor do atributo da ação classe deve ser um nome completo de uma classe Java que implementa org.eclipse.ui.IObjectActionDelegate no caso de contribuições de objetos, org.eclipse.ui.IViewActionDelegate para contribuições a visualizadores que pertencem a exibições, ou org.eclipse.ui.IEditorActionDelegate para contribuições para visualizadores que pertençam 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 necessário.

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

    Extensão do menu popup dentro de uma parte somente é possível quando a parte de destino publica um menu para extensão.   Isso é imensamente encorajado, uma vez que ele aumenta a extensibilidade do produto.   Para realizar isso, cada parte deve publicar qualquer menu popup que for definido ao chamar IWorkbenchPartSite#registerContextMenu.  Feito isso, o workbench inserirá automaticamente qualquer das extensões de ação que existir.

    Uma identificação de menu deve ser fornecida 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 popup que seja registrado com o workbench também deve conter um ponto de inserção padrão com a identificação 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 incluindo-se um GroupMarker ao menu na localização apropriada para inserção.

    Um objeto no workbench que seja a seleção em um menu de contexto pode definir um org.eclipse.ui.IActionFilter.  Essa é a estratégia de filtragem que pode executar filtragem de tipo especificado.  O workbench recuperará o filtro para a seleção ao testar para ver se ele implementa IActionFilter.  Se isso falhar, o workbench perguntará pelo filtro através do mecanismo IAdaptable.

    Implementação Fornecida: a exibição do workbench tem menus popup internos que já vêm carregados com um número de 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 popup.

    Copyright IBM Corp. 2000, 2001.  Todos os Direitos Reservados.