Conjuntos de Ação
Identificador: org.eclipse.ui.actionSets
Descrição: esse ponto de extensão é utilizado para incluir menus, itens de menu e botões da barra de ferramentas para áreas comuns na janela workbench. Essas contribuições são conhecidas coletivamente como conjunto de ação e aparecem dentro da janela do workbench de acordo com a preferência do usuário.
Marcação da Configuração:
<!ELEMENT actionSet (menu)* (action)* (description?)>
<!ATTLIST actionSet
id CDATA
#REQUIRED
label CDATA #REQUIRED
visible (true
| false) #IMPLIED
>
<!ELEMENT description (#PCDATA)>
-
id - um único nome que será utilizado para identificar esse conjunto de ação.
-
label - um nome traduzível que será utilizado no menu janela workbench para representar esse conjunto de ação.
-
visible - atributo opcional indicando se o conjunto de ação deve estar inicialmente visível na janela do workbench. O usuário pode substituir essa opção em "Personalizar Perspectiva de Diálogo".
-
description - subelemento opcional cujo corpo deve conter um texto fornecendo uma breve descrição do conjunto de ações.
<!ELEMENT menu (separator)+>
<!ATTLIST menu
id
CDATA #REQUIRED
label
CDATA #REQUIRED
path
CDATA #IMPLIED
>
-
id - um único identificador que pode ser utilizado para referir-se a esse menu.
-
label - uma etiqueta de texto de um novo menu. A etiqueta deve incluir informações mnemônicas.
-
path - a localização do menu iniciando a partir da raiz da barra de menus. Se omitido, o menu será incluído entre os menus Perspectiva e Janela na barra de menus. Cada token no caminho precisa referir-se a um menu existente no workbench, exceto o último, que deve representar um grupo nomeado no último menu no caminho.
<!ELEMENT separator EMPTY>
<!ATTLIST separator
name
CDATA #REQUIRED
>
name - nome do separador que pode mais tarde ser referido como último token no caminho da ação. Desse modo, os separadores servem como grupos nomeados dentro dos quais as ações e os sub-menus podem ser incluídos.
<!ELEMENT action (selection)*>
<!ATTLIST action
id
NMTOKEN #REQUIRED
label
CDATA #REQUIRED
menubarPath
CDATA #IMPLIED
toolbarPath
CDATA #IMPLIED
icon
CDATA #IMPLIED
tooltip
CDATA #IMPLIED
helpContextId
CDATA #IMPLIED
state
(true | false) #IMPLIED
pulldown
(true | false) #IMPLIED
class
CDATA #REQUIRED
enablesFor
CDATA #IMPLIED
>
-
id - identificador único que pode ser utilizado como uma referência para essa ação.
-
label - nome transferível que é utilizado de diversas maneiras, dependendo do contexto. Nos menus, é utilizado como um texto do menu. Nas barras de ferramentas, é utilizado como etiqueta do botão. A etiqueta pode conter Jface mnemônica codificada e informações do acelerador
(consulte exemplo).
-
menubarPath - caminho delimitado por atalho barra ('/') utilizado para especificar a localização da ação na barra de menus. Cada token no caminho, exceto o último, deve representar um ID válido de um menu existente na hierarquia. O último token representa o grupo separador nomeado dentro do qual a ação será incluída. Se um caminho for omitido, a ação não aparecerá na barra de menus.
-
toolbarPath - um caminho delimitado por atalho barra ('/') utilizado para especificar a localização da ação na barra de ferramentas.
O primeiro token representa o ID da barra de ferramentas (com "Normal" sendo a barra de ferramentas padrão), enquanto o segundo token é o grupo nomeado dentro da barra de ferramentas. Se um grupo não existir na barra de ferramentas, ele será criado.
Se o toolbarPath for omitido, a ação não aparecerá na barra de ferramentas.
-
icon - caminho relativo de um ícone que será utilizado para representar visualmente a ação em seu contexto.Se estiver omitido e a ação tiver que aparecer na barra de ferramentas, o workbench utilizará um ícone demarcador. O caminho é relativo em relação à localização do arquivo plugin.xml do plug-in de contribuição.
-
tooltip - valor do texto da descrição de ferramenta se a ação tiver que aparecer na barra de ferramentas.
De outra forma, ela é ignorada.
-
helpContextId - identificador único indicando a identificação do contexto de ajuda para essa ação. Se a ação aparecer como um item do menu, então ao pressionar F1 enquanto o item do menu estiver em destaque irá exibir a ajuda para a identificação do contexto fornecido.
-
state - atributo opcional indicando que a ação deveria ser do tipo comutação. Quando incluído no menu, ele se manifestará como um item da caixa de entrada. Quando incluído em uma barra de ferramentas, ele se tornará um botão de comutação. Se definido, o valor do atributo será utilizado como estado inicial verdadeiro
ou falso). Esse atributo é mutuamente exclusivo com pulldown.
-
pulldown - atributo opcional indicando que a ação tem um menu pulldown opcional. Se a ação aparecer em uma barra de ferramentas e o valor do atributo for verdadeiro, o menu pulldown aparecerá ao lado da ação.
Se a ação aparecer em um menu, esse atributo será ignorado.
Esse atributo é mutuamente exclusivo com estado.
-
class - nome completo de uma classe que implementa org.eclipse.ui.IWorkbenchWindowActionDelegate
ou org.eclipse.ui.IWorkbenchWindowPulldownDelegate. O último deve ser
implementado em casos onde pulldown for verdadeiro.
-
enablesFor - valor indicando a contagem da seleção que deve ser encontrada para ativar a ação. Se este atributo for especificado e a condição for encontrada, a ação é ativada. Se a condição não for encontrada, a ação é desativada.
Se nenhum atributo for especificado, a ação é ativada para qualquer número de itens selecionado. Os formatos de atributo a seguir são suportados:
! - 0 itens selecionados
? - 0 ou 1 item selecionado
+ - 1 ou mais itens selecionados
múltiplos, 2+ - 2 ou mais itens selecionados
n - um número preciso de itens selecionado. Exemplo: 4.
* - qualquer número de itens selecionados
<!ELEMENT selection EMPTY>
<!ATTLIST selection
class
CDATA #REQUIRED
name
CDATA #IMPLIED
>
-
class - nome completo da classe ou interface que cada objeto na seleção deve se subclassificar ou implementar a fim de ativar a ação.
-
name - filtro de caracteres curinga para o nome que pode ser aplicado opcionalmente para objetos na seleção. Se esse filtro for especificado e a correspondência falhar, a ação será ignorada.
É importante notar que o workbench não gera menus em favor do plug-in: os caminhos do menu referem-se a menus que já existem.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:
-
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 caracter &.
-
Os aceleradores opcionais são especificados ao final da cadeia de nome, utilizando @
seguido por uma série de modificadores e caracter de acelerador final (por exemplo)
&Save@Ctrl+S). O modificador pode ser colocado em cadeia, utilizando-se o sinal '+' como delimitador (como em @Ctrl+Shift+S).
Exemplos:
A seguir um exemplo de um conjunto de ações (note que os subelementos e os atributos de modo são utilizados):
<extension point = "org.eclipse.ui.actionSets">
<actionSet id="com.xyz.actionSet"
label="My Actions"
visibel="true">
<menu id ="com.xyz.xyzMenu"
label="XYZ Menu"
path="additions">
<separator name="group1"/>
</menu>
<action id="com.xyz.runXYZ"
label="&Run XYZ Tool"
menubarPath="com.xyz.xyzMenu/group1"
toolbarPath="Normal/XYZ"
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>
</actionSet>
</extension>
No exemplo acima, a ação especificada, nomeada "Minhas Ações", está inicialmente visível dentro de cada perspectiva. Ela somente será ativada para uma única seleção (atributo enablesFor). Além disso, os objetos dentro da seleção devem implementar a interface especificada (IFile) e devem ser um arquivo Java.
Informações de API: o valor do atributo de classe deve ser o nome completo de uma classe que implementa org.eclipse.ui.IWorkbenchWindowActionDelegate
ou org.eclipse.ui.IWorkbenchWindowPulldownDelegate. A última deve ser implementada em casos onde pulldown é verdadeiro.
Essa classe é carregada o mais tarde possível para evitar o carregamento de todo o plug-in antes que isso seja realmente necessário.
Implementação Fornecida: os Plug-ins podem utilizar esse ponto de extensão para incluir novos menus de nível superior
(por exemplo, Depurar). 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-se os seguintes valores para o atributo caminho:
-
additions - representam um grupo à esquerda do menu da janela.
A omissão do atributo path resultará na inclusão de um novo menu dentro do 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 em código para contribuição dinâmica.
Os valores também podem ser copiados para um arquivo XML para uma melhor integração com os menus do workbench e barra de ferramentas existentes.
Diversos itens do menu e da barra de ferramentas dentro da janela do workbench são definidos em forma de algorítmico. Nesses casos, um mecanismo separado precisa 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 aparecendo no menu Perspectiva. As extensões Importar, Exportar e Novos Assistentes também são incluídas automaticamente à janela.