Menus Editor, Barra de Ferramentas e Ações
Identificador: org.eclipse.ui.editorActions
Descrição: esse ponto de extensão é utilizado para incluir ações ao menu e à barra de ferramentas para editores registrados por outros plug-ins.
O conjunto de contribuição inicial para um editor é definido por outro ponto de extensão. (org.eclipse.ui.editors).
Um conjunto de ações é criado e compartilhado por todas as ocorrências de um mesmo tipo de editor. Quando chamado, essas ações agem sobre o editor ativo.
Esse ponto de extensão segue o mesmo padrão. Casa extensão de ação é criada e dividida por todas as ocorrências do mesmo tipo de editor. A classe de ação é necessária para implementar
org.eclipse.ui.IEditorActionDelegate.
O editor ativo é transmitido para o delegado chamando-se IEditorActionDelegate#setActiveEditor.
Marcação da Configuração:
<!ELEMENT editorContribution (menu | action)*>
<!ATTLIST editorContribution
id
CDATA #REQUIRED
targetID CDATA #REQUIRED
>
id - único identificador que pode ser utilizado para referir-se a essa contribuição.
editorID - identificador único de um editor previamente registrado que é destino dessa contribuição.
<!ELEMENT menu (separator)+>
<!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 - a etiqueta do texto do novo menu. A etiqueta deve incluir informações mnemônicas.
-
path - localização da inicialização do menu a partir da raiz da barra de menus. Se omitido, o menu será incluído dentro do slot additions
na barra de menus. Cada token no caminho refere-se a um menu existente na plataforma, exceto a última , que representa 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.
Assim sendo, os separadores servem como grupos nomeados cujas ações podem ser incluídas.
<!ELEMENT action (selection)* (enablement)?>
<!ATTLIST action
id
NMTOKEN #REQUIRED
label
CDATA #REQUIRED
accelerator
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
class
CDATA #REQUIRED
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 - o acelerador da ação. Este é especificado
como uma combinação de teclas CTRL, SHIFT e ALT e uma tecla de atalho.
Esses valores não são internazionalizados e não devem ser convertidos. A especificação
do acelerador para o título de entrada deve ser feita no rótulo - esse
valor não será utilizado para construir uma entrada de menu.
-
menubarPath - um caminho absoluto delimitado por barra ('/') utilizado para
especificar a localização da ação na barra de menus. O caminho pode somente
apontar para menus que pertençam a um editor de destino. O último token representa o grupo separador nomeado dentro do qual a ação será incluída.
Se o 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á.
-
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 do plug-in contribuinte.
-
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 do plug-in contribuinte.
-
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 - utilizado se a ação estiver para aparecer na barra de ferramentas. Do contrário, 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 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 a 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).
-
class - nome de uma classe completa que implementa org.eclipse.ui.IEditorActionDelegate.
-
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 caracter curinga que pode opcionalmente ser aplicado a 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 ação. Para obter mais informações sobre
o uso do elemento de ativação, consulte actionExpressions.html.
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.
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 &.
-
Acelerados opcionais são especificados ao final de uma cadeia nomeada, utilizando @
seguido de uma série de modificadores e o caracter do acelerador final (por exemplo, &Save@Ctrl+S). Os modificadores podem ser colocados 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.
Exemplos:
A seguir um exemplo de um ponto de extensão da ação do editor.
<extension point="org.eclipse.ui.editorActions">
<editorContribution
id="com.xyz.xyzContribution"
targetID="com.ibm.XMLEditor">
<menu id="XYZ"
label="&XYZ Menu">
<separator name="group1"/>
</menu>
<action
id="com.xyz.runXYZ"
label="&Run XYZ Tool"
menubarPath="XYZ/group1"
toolbarPath="Normal/additions"
state="true"
icon="icons/runXYZ.gif"
tooltip="Run XYZ Tool"
helpContextId="com.xyz.run_action_context"
class="com.xyz.actions.RunXYZ">
</action>
</editorContribution>
</extensão>
No exemplo acima, a ação especificada aparecerá como um item da caixa de opção
no novo menu de nível superior nomeado "Menu XYZ" e como um botão de comutação
na barra de ferramentas.
A seguir um exemplo de um ponto de extensão da ação do editor.
<extension point="org.eclipse.ui.editorActions">
<editorContribution
id="com.xyz.xyz2Contribution"
targetID="com.ibm.XMLEditor">
<menu
id="XYZ2"
label="&XYZ2 Menu"
path="edit/additions">
<separator name="group1"/>
</menu>
<action
id="com.xyz.runXYZ2"
label="&Run XYZ2 Tool"
menubarPath="edit/XYZ2/group1"
state="true"
icon="icons/runXYZ2.gif"
tooltip="Executar a Ferramenta XYZ2"
helpContextId="com.xyz.run_action_context2"
class="com.xyz.actions.RunXYZ2">
</action>
</editorContribution>
</extensão>
No exemplo acima, a ação especificada aparecerá como um item da caixa de opção
no submenu nomeado "Menu XYZ2" no menu "Editar" do nível superior.
Informações de API: o valor do atributo de classe deve ser um nome completo de uma classe Java que implementa org.eclipse.ui.IEditorActionDelegate.
Essa interface é carregada o mais tarde possível para evitar o carregamento de todo o plug-in antes que isso seja necessário. O método setActiveEditor
será chamado toda vez que um editor de um tipo especificado for ativado. Somente um conjunto de ações e menus será criado para todas as ocorrências para o tipo de editor especificado, não importando o número das ocorrências do editor atualmente abertas na plataforma.
Esse ponto de extensão pode ser utilizado para contribuir com ações dentro de menus previamente criados pelo editor de destino. Além disso, os menus e as ações podem contribuir com a janela do workbench. Os identificadores para ações e grupos maiores dentro da janela do workbench são definidos em org.eclipse.ui.IWorkbenchActionConstants.
Isso deve ser utilizado como ponto de referência para a inclusão de novas ações.
Menus de nível máximo são criados utilizando-se os seguintes valores para o atributopath:
-
additions - representam um grupo à esquerda do menu Janela.
As ações e os menus incluídos dentro desses caminhos somente serão mostrados enquanto o editor associado estiver ativo. Quando o editor for fechado, os menus e as ações serão removidos. Implementação Fornecida: o workbench fornece um "Editor de Texto Padrão" interno. Os Plug-ins podem contribuir dentro desse editor padrão ou editores fornecidos por outros plug-ins.