Exibir Menus, Barra de Ferramentas e Ações
Identificador: org.eclipse.ui.viewActions
Descrição: esse ponto de extensão é utilizado para incluir ações no menu e na barra de ferramentas para exibições registradas por outros plug-ins. Cada exibição tem um menu pulldown local normalmente ativado ao clicar na área superior direita. Outros plug-ins podem contribuir com sub-menus e ações para esse menu. Os plug-ins também podem contribuir com ações para a barra de ferramentas de exibição. Aos proprietários de exibições é dada a primeira chance de ocupar essas áreas.
Inclusões opcionais por outros plug-ins são anexadas.
Marcação da Configuração:
<!ELEMENT viewContribution (menu | action)*>
<!ATTLIST viewContribution
id
CDATA #REQUIRED
targetID CDATA #REQUIRED
>
id - único identificador que pode ser utilizado para referir-se a essa contribuição.
targetID - identificador único da exibição (conforme especificado no registro) dentro do qual a contribuição é feita.
<!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 - a localização da inicialização do menu a partir do pulldown, com o último token representando o grupo nomeado. Se omitido, o menu será incluído ao final do pulldown.
<!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 dentro dos quais as ações podem ser incluídas.
<!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
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. 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 no menu pulldown. Cada token no caminho, exceto o último, representa um menu existente na hierarquia.
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á no pulldown.
-
toolbarPath - grupo nomeado dentro da barra de ferramentas local da exibição de destino. Se o grupo não existir, ele será criado. Se omitido, a ação não aparecerá na barra de ferramentas local.
-
icon - um caminho relativo para um ícone que será utilizado para representar visualmente a ação em seu contexto. Se omitido e se a ação tiver que aparecer na barra de ferramentas local, o workbench utilizará um ícone demarcador. O caminho é relativo à localização do arquivo
plugin.xml file do plug-in de contribuição.
-
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 (ou verdadeiro
ou falso).
-
tooltip - utilizada se a ação tiver que aparecer na barra de ferramentas local.
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.
-
class - nome de classe completo que implementaorg.eclipse.ui.IViewActionDelegate.
-
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.
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 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 traduzível.
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). Os modificadores podem ser colocados em cadeia, utilizando-se o sinal '+' como delimitador (como em @Ctrl+Shift+S).
Exemplos:
A seguir um exemplo do ponto de extensão de uma exibição (note que os subelementos e os atributos de modo são utilizados):
<extension point="org.eclipse.ui.viewActions">
<viewContribution
id="com.xyz.xyzViewC1"
targetID="org.eclipse.ui.views.navigator.ResourceNavigator">
<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>
</viewContribution>
</extension>
No exemplo acima, a ação especificada somente ativará uma seleção simples (atributo enablesFor). Além disso, cada objeto nessa seleção deve implementar a interface especificada. (IFile)
e deve ser um arquivo Java. Elementos múltiplos seleção podem ser especificados, significando 'um de'.
Informações de API: o valor do atributo de classe deve ser um nome completo de uma classe Java que implementa org.eclipse.ui.IViewActionDelegate.
Essa interface é carregada o mais tarde possível para evitar o carregamento de todo o plug-in antes que isso seja necessário. Ela estende org.eclipse.ui.IActionDelegate
e inclui um método adicional que permite ao delegado inicializar com a ocorrência de exibição de sua contribuição interna.
Implementação Fornecida: cada visualização normalmente vem com um número de itens padrão no menu pulldown e na barra de ferramentas local.
Inclusões a partir dos plug-ins serão anexadas ao complemento padrão.
É útil para publicar os identificadores de ação para uma exibição dentro de uma interface pública. Por exemplo, as ações e os principais grupos para a janela do workbench são definidos em org.eclipse.ui.IWorkbenchActionConstants.