Conjuntos de Acções

org.eclipse.ui.actionSets

Este ponto de extensão é utilizado para adicionar menus, artigos de menu e botões de barra de ferramentas às áreas comuns na janela Área de trabalho. Estas contribuições são conhecidas colectivamente como umconjunto de acções e aparecem dentro da janela Área de trabalho, quando o utilizador personaliza uma perspectiva.

Existe uma limitação de implementação que actualmente afecta os conjuntos de acção. É importante definir a estrutura do menu a ser referida no conjunto da acção. Assim sendo, por exemplo, se outro conjunto de acções define um menu denominado "exemplo", não é possível depender de um "exemplo" existente. É necessário redefinir o menu "exemplo" em cada conjunto de acção que o pretender utilizar.

A activação e/ou visibilidade de uma acção pode ser definida utilizando os elementos enablement e visibility, respectivamente. Estes dois elementos contêm uma expressão booleana que é avaliada para determinar a activação e/ou visibilidade.

A sintaxe é igual para os elementos enablement e visibility. Ambos contêm apenas um subelemento de expressão booleana. No caso mais simples, este 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. Tanto o elemento and como o elemento or têm de conter dois subelementos. O elemento not tem de conter apenas um subelemento.

<!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>

Este elemento é utilizado para definir um grupo de acçõ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>

Este elemento define uma acção que o utilizador pode invocar na UI.



<!ELEMENT menu (separator+ , groupMarker*)>

<!ATTLIST menu

id    CDATA #REQUIRED

label CDATA #REQUIRED

path  CDATA #IMPLIED>

Este elemento é utilizado para definir um novo menu.



<!ELEMENT separator EMPTY>

<!ATTLIST separator

name CDATA #REQUIRED>

Este elemento é utilizado para criar um separador de menu no novo menu.



<!ELEMENT groupMarker EMPTY>

<!ATTLIST groupMarker

name CDATA #REQUIRED>

Este elemento é utilizado para criar um grupo designado no novo menu. Não tem qualquer representação visual no novo menu, ao contrário do elemento separator.



<!ELEMENT selection EMPTY>

<!ATTLIST selection

class CDATA #REQUIRED

name  CDATA #IMPLIED>

Este elemento é utilizado para ajudar a determinar a activação de acção, com base na selecção actual. É ignorado se o elemento enablement estiver especificado.



<!ELEMENT enablement (and | or | not | objectClass | objectState | pluginState | systemProperty)>

Este elemento é utilizado para definir a activação da extensão.



<!ELEMENT visibility (and | or | not | objectClass | objectState | pluginState | systemProperty)>

Este elemento é utilizado para definir a visibilidade da extensão.



<!ELEMENT and (and | or | not | objectClass | objectState | pluginState | systemProperty)>

Este elemento representa uma operação AND booleana no resultado de avaliação das duas expressões de subelemento respectivas.



<!ELEMENT or (and | or | not | objectClass | objectState | pluginState | systemProperty)>

Este elemento representa uma operação OR booleana no resultado de avaliação das duas expressões de subelemento respectivas.



<!ELEMENT not (and | or | not | objectClass | objectState | pluginState | systemProperty)>

Este elemento representa uma operação NOT booleana no resultado de avaliação das expressões de subelemento respectivas.



<!ELEMENT objectClass EMPTY>

<!ATTLIST objectClass

name CDATA #REQUIRED>

Este elemento é utilizado para avaliar a classe ou interface de cada objecto na selecção actual. Se cada objecto da selecção implementar a classe ou interface especificadas, a expressão é avaliada como true.



<!ELEMENT objectState EMPTY>

<!ATTLIST objectState

name  CDATA #REQUIRED

value CDATA #REQUIRED>

Este elemento é utilizado para avaliar o estado do atributo de cada objecto na selecção actual. Se cada objecto da selecção possuir o estado de atributo especificado, a expressão é avaliada como true. Para avaliar este tipo de expressão, cada objecto na selecção tem de implementar ou adaptar-se à interface org.eclipse.ui.IActionFilter.



<!ELEMENT pluginState EMPTY>

<!ATTLIST pluginState

id    CDATA #REQUIRED

value (installed|activated) "installed">

Este elemento é utilizado para avaliar o estado de um conector. O estado do conector 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>

Este elemento é utilizado para avaliar o estado de algumas propriedades do sistema. O valor property é obtido a partir de java.lang.System.



De seguida é apresentado um exemplo de um conjunto de acções (tenha em consideração os subelementos e a forma como os atributos são utilizados):

    

<extension point =

"org.eclipse.ui.actionSets"

>

<actionSet id=

"com.xyz.actionSet"

label=

"As Minhas Acções"

>

<menu id=

"com.xyz.xyzMenu"

label=

"XYZ Menu"

path=

"additions"

>

<separator name=

"group1"

/>

<separator name=

"option1"

/>

</menu>

<action id=

"com.xyz.runXYZ"

label=

"&amp;Run XYZ Tool"

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=

"&amp;Executar Ferramenta ABC"

style=

"push"

menubarPath=

"com.xyz.xyzMenu/group1"

toolbarPath=

"Normal/XYZ"

icon=

"icons/runABC.gif"

tooltip=

"Executar Ferramenta ABC"

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=

"&amp;Executar Ferramenta DEF"

style=

"radio"

state=

"true"

menubarPath=

"com.xyz.xyzMenu/option1"

icon=

"icons/runDEF.gif"

tooltip=

"Executar Ferramenta DEF"

class=

"com.xyz.actions.RunDEF"

helpContextId=

"com.xyz.run_def_action_context"

>

</action>

<action id=

"com.xyz.runGHI"

label=

"&amp;Executar Ferramenta GHI"

style=

"radio"

state=

"false"

menubarPath=

"com.xyz.xyzMenu/option1"

icon=

"icons/runGHI.gif"

tooltip=

"Executar Ferramenta GHI"

class=

"com.xyz.actions.RunGHI"

helpContextId=

"com.xyz.run_ghi_action_context"

>

</action>

<action id=

"com.xyz.runJKL"

label=

"&amp;Executar Ferramenta JKL"

style=

"radio"

state=

"false"

menubarPath=

"com.xyz.xyzMenu/option1"

icon=

"icons/runJKL.gif"

tooltip=

"Executar Ferramenta JKL"

class=

"com.xyz.actions.RunJKL"

helpContextId=

"com.xyz.run_jkl_action_context"

>

</action>

</actionSet>

</extension>

No exemplo anterior, o conjunto de acções especificado, designado "As Minhas Acções", não está inicialmente visível dentro de cada perspectiva, dado que o atributo visible não está especificado.

A acção XYZ irá aparecer como um artigo de menu de caixa de verificação, que inicialmente não está seleccionado. Só se activará caso o total de selecções seja 1 e caso a selecção contenha um recurso de ficheiro Java.

A acção ABC aparecerá no menu e na barra de ferramentas. Só se activará caso a selecção não contenha quaisquer recursos de ficheiro Java. Tenha também em atenção que esta é uma acção de redireccionamento de etiqueta e, consequentemente, não faculta um atributo class.

As acções DEF, GHI e JKL aparecem como artigos de menu de botão de selecção. Estão constantemente activadas, independentemente do estado de selecção actual.

O valor do atributo de classe tem de ser um nome totalmente qualificado de uma classe que implemente org.eclipse.ui.IWorkbenchWindowActionDelegate ou org.eclipse.ui.IWorkbenchWindowPulldownDelegate. O último deve ser implementado em casos em que o atributo style possui o valor pulldown. Esta classe é o operador responsável pela execução da acção. Caso o atributo retarget seja true, este atributo é ignorado e não deve ser facultado.Esta classe é carregada o mais tarde possível, para evitar carregar a totalidade do conector antes que seja realmente necessário.

Os critérios de activação para uma extensão de acção são inicialmente definidos por enablesFor, e também por selection ou enablement. No entanto, quando o delegado de acção tiver sido dividido em instâncias, poderá controlar o estado de activação da acção directamente dentro do respectivo método selectionChanged.

É importante ter em conta que a área de trabalho não gera menus em nome de um plug-in. Os caminhos de menu têm de referenciar menus que já existem.

As etiquetas de acções e menus podem conter caracteres especiais que codifiquem mnemónicas, utilizando as seguintes regras:

  1. As mnemónicas são especificadas utilizando o carácter de e comercial ('&') antes de um carácter seleccionado no texto traduzido. Dado que e comercial não é permitido em cadeias XML, utilize a entidade de carácter &amp;.
Caso uma única extensão contribua com duas ou mais acções para um menu ou barra de ferramentas, as acções aparecerão segundo uma ordem contrária àquela em que estão enumeradas no ficheiro plugin.xml. Este comportamento é reconhecidamente não intuitivo. No entanto, foi descoberto após a API da Plataforma Eclipse ter sido congelada. A alteração deste comportamento iria provocar danos em todos os conectores que se baseiam nesse comportamento.

Os elementos selection e enablement excluem-se mutuamente. O elemento enablement pode substituir o elemento selection utilizando os subelementos objectClass e objectState. Por exemplo, o seguinte código:

 

<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>

Os plug-ins podem utilizar este ponto de extensão para adicionar novos menus de nível superior. Os plug-ins também podem definir grupos designados que permitem a outros plug-ins contribuir com as suas acções para estes grupos.

Os menus de nível superior são criadas utilizando os valores seguintes para o atributo path:

Ao omitir o tributo path, o novo menu será adicionado ao grupo additions da barra de menus.

Os grupos predefinidos numa janela da área de trabalho estão definidos na interface IWorkbenchActionConstants. Estas constantes podem ser utilizadas em código para uma contribuição dinâmica. Os valores também podem ser copiados para um ficheiro XML, de modo a obter uma integração mais precisa com os existentes menus e barra de ferramentas da área de trabalho.

Vários artigos de menu e de barra de ferramentas dentro da janela da área de trabalho estão definidos algoritmicamente. Nestes caso tem de ser utilizado um mecanismo distinto para expandir a janela. Por exemplo, adicionar uma nova vista da área de trabalho gera um novo artigo de menu que surge no menu Perspectiva. As extensões de Importar, Exportar e Novos Assistentes também são adicionadas automaticamente à janela.