Esse ponto de extensão é utilizado para incluir menus, itens de menu e botões da barra de ferramentas em áreas comuns na janela do Ambiente de Trabalho. Essas contribuições são conhecidas coletivamente como um conjunto de ações e são exibidas dentro da janela do Ambiente de Trabalho pelo usuário que está personalizando uma perspectiva.
Há uma limitação de implementação que afeta atualmente os conjuntos de ações. É importante definir toda a estrutura de menu que será referida no conjunto de ações. Assim, por exemplo, se outro conjunto de ações definir um menu chamado "exemplo", não será possível contar com o "exemplo" existente. É necessário redefinir o menu "exemplo" em cada conjunto de ações que deseja utilizá-lo.
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.
<!ELEMENT extension (actionSet+)>
<!ATTLIST extension
point CDATA #REQUIRED
id CDATA #IMPLIED
name CDATA #IMPLIED>
<!ELEMENT actionSet (menu* , action*)>
<!ATTLIST actionSet
id CDATA #REQUIRED
label CDATA #REQUIRED
visible (true | false)
description CDATA #IMPLIED>
Esse elemento é utilizado para definir um grupo de ações e/ou menus.
<!ELEMENT action (selection* | enablement?)>
<!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>
Esse elemento define uma ação que o usuário pode chamar na UI.
push | - como um item de menu ou de ferramenta normal. | |
radio | - como um item de menu ou de ferramenta no estilo de opções. As ações com o estilo de opções no mesmo grupo de menu ou barra de ferramentas se comportam como um conjunto de opções. O valor inicial é especificado pelo atributo state. | |
toggle | - como um item de menu ou de ferramenta de comutação no estilo de marcação. O valor inicial é especificado pelo atributo state. | |
pulldown | - como um item de menu com estilo em cascata ou como um menu drop down ao lado do item de ferramenta. |
! | - 0 itens selecionados | |
? | - 0 ou 1 item selecionado | |
+ | - 1 ou mais itens selecionados | |
vários, 2+ | - 2 ou mais itens selecionados | |
n | - um número preciso de itens selecionado. Por exemplo: enablesFor=" 4" ativa a ação apenas quando 4 itens forem selecionados | |
* | - qualquer número de itens selecionados |
<!ELEMENT menu (separator+ , groupMarker*)>
<!ATTLIST menu
id CDATA #REQUIRED
label CDATA #REQUIRED
path CDATA #IMPLIED>
Esse elemento é utilizado para definir um novo menu.
<!ELEMENT separator EMPTY>
<!ATTLIST separator
name CDATA #REQUIRED>
Esse elemento é utilizado para criar um separador de menu no novo menu.
<!ELEMENT groupMarker EMPTY>
<!ATTLIST groupMarker
name CDATA #REQUIRED>
Esse elemento é utilizado para criar um grupo nomeado no novo menu. Não há representação visual no novo menu, diferentemente do elemento separator.
<!ELEMENT selection EMPTY>
<!ATTLIST selection
class CDATA #REQUIRED
name CDATA #IMPLIED>
Esse elemento é utilizado para ajudá-lo a determinar a ativação da ação com base na seleção atual. É ignorado se o elemento enablement for especificado.
<!ELEMENT enablement (and | or | not | objectClass | objectState | pluginState | systemProperty)>
Esse elemento é utilizado para definir a ativação da extensão.
<!ELEMENT visibility (and | or | not | objectClass | objectState | pluginState | systemProperty)>
Esse elemento é utilizado para definir a visibilidade da extensão.
<!ELEMENT and (and | or | not | objectClass | objectState | pluginState | systemProperty)>
Esse 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)>
Esse 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)>
Esse elemento representa uma operação booleana NOT no resultado da avaliação de expressões de subelementos.
<!ELEMENT objectClass EMPTY>
<!ATTLIST objectClass
name CDATA #REQUIRED>
Esse 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 interface especificada, a expressão será avaliada como verdadeira.
<!ELEMENT objectState EMPTY>
<!ATTLIST objectState
name CDATA #REQUIRED
value CDATA #REQUIRED>
Esse elemento é utilizado para avaliar o estado de 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.
<!ELEMENT pluginState EMPTY>
<!ATTLIST pluginState
id CDATA #REQUIRED
value (installed|activated) "installed">
Esse elemento é utilizado para avaliar o estado de um plug-in. O estado do plug-in pode ser um dos seguintes: installed (equivalente ao conceito OSGi de "resolved") ou activated (equivalente ao conceito OSGi de "active").
<!ELEMENT systemProperty EMPTY>
<!ATTLIST systemProperty
name CDATA #REQUIRED
value CDATA #REQUIRED>
Esse elemento é utilizado para avaliar o estado de alguma propriedade do sistema. O valor da propriedade é recuperado de java.lang.System.
<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=
"&Executar Ferramenta XYZ"
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=
"&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=
"&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=
"&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=
"&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.
Os critérios de ativação para uma extensão de ação é inicialmente definida por enablesFor e também por selection ou enablement. 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 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.
Os rótulos das ações e de menus podem conter caracteres especiais que codificam mnemônicos utilizando as seguintes regras:
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:
pode ser expresso utilizando:<selection class=
"org.eclipse.core.resources.IFile"
name=
"*.java"
>
</selection>
<enablement>
<and>
<objectClass name=
"org.eclipse.core.resources.IFile"
/>
<objectState name=
"extension"
value=
"java"
/>
</and>
</enablement>
Menus de nível superior são criados utilizando os seguintes valores para o atributo path:
Os grupos padrão em uma janela do Ambiente de Trabalho 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 Ambiente de Trabalho 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.
Direitos Autorais (c) 2000, 2004 IBM Corporation e outros.
Todos os direitos reservados. Este programa e os materiais fornecidos com ele são
disponibilizados sob os termos da Licença Pública do Eclipse v1.0 que acompanha
esta distribuição e está disponível em
http://www.eclipse.org/legal/epl-v10.html