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 - um atributo opcional indicando se o conjunto de ações
deve estar inicialmente visível em todas as perspectivas. Essa opção
apenas será respeitada quando o usuário abrir uma nova perspectiva que não foi
personalizada. O usuário também 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)+ (groupMarker)*>
<!ATTLIST menu
id
CDATA #REQUIRED
label
CDATA #REQUIRED
path
CDATA #IMPLIED
>
-
id - ú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 antes do menu
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 o ú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 groupMarker EMPTY>
<!ATTLIST groupMarker
name
CDATA #REQUIRED
>
name - um nome do marcador de grupo que pode, posteriormente, ser mencionado como
o último token no caminho de ação.
<!ELEMENT action (selection)* (enablement)?>
<!ATTLIST action
id
NMTOKEN #REQUIRED
label
CDATA #REQUIRED
accelerator
CDATA #IMPLIED
definitionId
CDATA #IMPLIED
menubarPath
CDATA #IMPLIED
toolbarPath
CDATA #IMPLIED
icon
CDATA #IMPLIED
disabledIcon
CDATA #OPTIONAL
hoverIcon
CDATA #OPTIONAL
tooltip
CDATA #IMPLIED
helpContextId
CDATA #IMPLIED
state
(true | false) #IMPLIED
pulldown
(true | false) #IMPLIED
class
CDATA #OPTIONAL
retarget
(true | false) #OPTIONAL
allowLabelUpdate
(true | false) #OPTIONAL
enablesFor
CDATA #IMPLIED
>
-
id - identificador único que pode ser utilizado como referência para essa ação.
-
label - nome traduzível que é utilizado de várias maneiras, dependendo do contexto. Em menus, ele é utilizado como texto do menu. Nas barras de ferramentas, é utilizado como etiqueta botão.
A etiqueta pode conter Jface mnemônica codificada e informações do acelerador
(consulte exemplo).
-
accelerator - um inteiro que é utilizado para especificar o código chave do
acelerador da ação. Esse é o valor do inteiro resultante de
um bitwise OU de zero ou mais máscaras do modificador de tecla SWT (isto é, SWT.CTRL ou SWT.ALT)
e um código de caracteres. Por exemplo, para Ctrl+Z utilize SWT.CTRL | 'Z' =
(1<<18)|'Z' = 262234.
-
definitionId - o ID especificado na definição de ação. Apenas necessário
quando um conjunto de ações especifica os aceleradores através do serviço de ligação por tecla. Consulte
os pontos de extensão Definições de Ações
e Conjuntos de Aceleradores
-
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 o 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 à localização do arquivo
plugin.xml file do plug-in de contribuição.
O ícone aparecerá nas barras de ferramentas e não nos menus. As ações ativadas
serão representadas nos menus pelo hoverIcon.
-
disabledIcon - caminho relativo de um ícone que será utilizado para representar
visualmente a ação em seu contexto quando ela está desativada. Se for
omitido, o ícone normal apenas aparecerá desativado. O caminho é relativo à localização do arquivo
plugin.xml file do plug-in de contribuição.
O ícone desativado aparecerá nas barras de ferramentas e não nos menus. Os ícones para as ações desativadas
nos menus serão fornecidos pelo OS.
-
hoverIcon - caminho relativo de um ícone que será utilizado para representar
visualmente a ação em seu contexto quando o mouse está sobre a ação.
Se for omitido, o ícone normal será utilizado. O caminho é relativo à localização do arquivo
plugin.xml do plug-in contribuinte.
-
tooltip - valor do texto da descrição de ferramenta se a ação tiver que aparecer na barra de ferramentas.
Do contrário, ela é ignorada.
-
helpContextId - identificador único indicando o id 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 ajuda para o id do contexto fornecido.
-
state - um atributo opcional indicando que a ação deve ser de tipo comutação.
Quando incluído em um menu, ele irá manifestar-se 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. Se o atributo retarget for verdadeiro, esse atributo não deverá ser fornecido.
-
retarget - se esse atributo for verdadeiro, uma ação retarget (global)
será criada.
As partes podem fornecer uma rotina de tratamento para esta ação global utilizando
o mecanismo padrão para definir uma rotina de tratamento de ação global em seu estado,
utilizando esse ID da ação. Se esse atributo for verdadeiro, o atributo class deverá
ser fornecido.
-
allowLabelUpdates - aplica-se apenas se retarget for verdadeiro. Se esse atributo
for verdadeiro, a ação retarget atualizará seu rótulo e descrição de ferramenta de sua
rotina de tratamento.
-
enablesFor - valor indicando a contagem da seleção que deve ser alcançada para ativar a ação. Se esse atributo for especificado e a condição alcançada, a ação é ativada. Se a condição não for alcançada, a ação é desativada.
Se nenhum atributo for especificado, a ação é ativada por qualquer número de itens selecionados. Os seguintes formatos de atributo 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
>
-
classe - nome completo da classe ou interface que cada objeto na seleção deve classificar como classe filha 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á desativada.
<!ELEMENT enablement (and | or | not | objectClass
| objectState | systemProperty | pluginState)*>
<!ATTLIST enablement EMPTY>
Na versão 2.0 de Eclipse, um elemento de ativação pode ser utilizado
para definir a ativação para ação. Para obter mais informações sobre
o uso do elemento de ativação, consulte actionExpressions.html.
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>
<action id="com.xyz.runABC"
label="&Run ABC Tool"
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">
</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.
Os critérios de ativação para a extensão de uma ação são inicialmente definidos
por
enablesFor, seleção e ativaçã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.
É importante notar que o workbench não gera menus em favor do
plug-ins: os caminhos do menu referem-se a menus que já existem.
A ação e a 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 caractere &.
-
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).
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 procedimento não é reconhecidamente intuitivo.
Entretanto, ele foi descoberto após a API da Plataforma Eclipse estava pendente.
Alterar o procedimento agora iria interromper cada plug-in que lida com o
procedimento existente.
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 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 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 aparecendo no menu Janela. As extensões Importar, Exportar e Novos Assistentes também são incluídas automaticamente à janela.