Menus

org.eclipse.ui.menus

3.2

Este ponto de extensão permite que o programador do plug-in defina menus, separadores, grupos lógicos e artigos do menu -- que aparecem em qualquer lugar dentro da aplicação, desde linhas de estado a menus contextuais. Permite também grupos dessas contribuições a ser definidas (ou seja, conjuntos de acções); estes conjuntos de acções podem ser ligados e desligados pelo utilizador final. Resumindo, o ponto de extremidade dos menus contém todos os elementos de apresentação (excepto os ícones) de contribuição para qualquer menu ou área de ajuste no Eclipse.

É atribuído um identificador exclusivo a todos os elementos neste ponto de extensão. Esta atribuição é feita para que estes elementos possam ser consultados em qualquer outro lugar sem ser necessário reformular o elemento. Por exemplo, o identificador pode ser requerido para ordenar ou definir um conjunto de acções. Permite também que programadores de plug-ins de terceiros coloquem estes elementos em novas localizações na interface de modo adequado.

NOTA: Na versão 3.2, a única parte deste mecanismo de extensão implementada é a parte associada às contribuições "trim". A tentativa de adicionar artigos, menus, barras de ferramentas ou entradas de linhas de estados irá agir como estando inoperativa.

<!ELEMENT extension (item* , menu* , group* , widget*)>

<!ATTLIST extension

point CDATA #REQUIRED

id    CDATA #IMPLIED

name  CDATA #IMPLIED>


<!ELEMENT item (parameter* , location* , visibleWhen?)>

<!ATTLIST item

id        CDATA #REQUIRED

commandId CDATA #REQUIRED

menuId    CDATA #IMPLIED>

Um artigo pode ser uma opção de menu ou de ajuste, dependendo do local onde é colocado. O texto e a imagem associados ao artigo serão retirados do comando.



<!ELEMENT menu (location* , visibleWhen?)>

<!ATTLIST menu

id    CDATA #REQUIRED

label CDATA #IMPLIED>

Um menu pode aparecer anexado a um artigo de ferramentas ou num menu de vistas, num menu contextual ou na barra de menus de nível superior. Automaticamente, o programador do plug-in pode presumir que existe um menu e uma barra de ferramentas para cada vista, assim como uma barra de menus de nível superior. Os menus contextuais têm de ser registados programaticamente antes de poderem ser utilizados (consulte Informações de API).

um menu apenas pode conter grupos.



<!ELEMENT group (location*)>

<!ATTLIST group

id                CDATA #REQUIRED

separatorsVisible (true | false) "true">

Um grupo lógico. Pode ser visível (como por exemplo, os separadores são retirados antes ou depois, conforme o modo adequado) ou invisível. Por predefinição, os grupos lógicos são visíveis.

Um grupo pode conter menus, artigos e outros grupos.



<!ELEMENT widget (location* , class? , visibleWhen? , layout?)>

<!ATTLIST widget

id    CDATA #REQUIRED

class CDATA #REQUIRED>

Um elemento menu ou trim ao qual é concedido acesso directo aos widgets. Por exemplo, pode ser utilizado para compor uma caixa de combinação. Infelizmente, isto significa que se um elemento widget se tornar visível na interface do utilizador, haverá um carregamento do plug-in. Utilize este elemento com cuidado, uma vez que pode causar problemas de desempenho. Pode também causar problemas no suporte macro, na criação de script e em qualquer outro mecanismo com base em comandos. Quando é utilizado como um ajuste, o widget também irá levar ao carregamento do plug-in quando este se tornar visível na UI.



<!ELEMENT layout EMPTY>

<!ATTLIST layout

fillMajor (true | false)

fillMinor (true | false) >

Este elemento pode ser utilizado para especificar várias opções de esquematização para os elementos adicionados a localizações trim.



<!ELEMENT location (order? , (bar | part | popup))>

<!ATTLIST localização

mnemonic   CDATA #IMPLIED

imageStyle CDATA #IMPLIED>

Uma localização em que pode aparecer um menu, um group, um item ou um widget. Este elemento é utilizado para controlar informações específicas da localização.



<!ELEMENT bar EMPTY>

<!ATTLIST bar

type (menu|trim)

path CDATA #IMPLIED>

Um elemento folha numa localização. Pode ser a barra de menu ou a área de ajuste. Se não for qualificado, indica a barra de menu ou de ajuste de nível superior. Se for qualificado com um elemento part, indica o menu ou ajuste dessa parte.



<!ELEMENT class (parameter*)>

<!ATTLIST class

class CDATA #REQUIRED>

Um elemento de classe que suporta a sintaxe de análise de extensão executável para os elementos widget e dynamic.



<!ELEMENT visibleWhen (not | or | and | instanceof | test | systemTest | equals | count | with | resolve | adapt | iterate)>

<!ATTLIST visibleWhen

checkEnabled (true | false) "false">

Controla a visibilidade de um determinado elemento.



<!ELEMENT part (popup | bar)>

<!ATTLIST part

id    CDATA #IMPLIED

class CDATA #IMPLIED>

Um elemento dentro de uma localização. Qualifica a localização para consultar uma determinada parte da área de trabalho. Essa parte pode ser uma vista ou um editor. A qualificação pode utilizar o nome de classe da parte (incluindo a herança) ou pode consultar o identificador da vista ou do editor.

Apenas pode definir um dos valores id e class.



<!ELEMENT parameter EMPTY>

<!ATTLIST parameter

name  CDATA #REQUIRED

value CDATA #REQUIRED>

Um parâmetro para uma extensão executável ou para um comando -- dependendo de onde aparece na extensão.



<!ELEMENT order EMPTY>

<!ATTLIST order

position   (start|end|before|after)

relativeTo CDATA #IMPLIED>

Controla a posição de um menu, grupo, artigo ou widget numa determinada localização.



<!ELEMENT popup EMPTY>

<!ATTLIST popup

id   CDATA #IMPLIED

path CDATA #IMPLIED>

Parte de uma localização. Indica que o menu, grupo, artigo ou widget deverá aparecer no menu emergente.



<!ELEMENT enablement (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>

Um elemento raiz genérico. O elemento pode ser utilizado dentro de um ponto de extensão para definir a respectiva expressão de activação. Os elementos descendentes de uma expressão de activação são combinados através da utilização do operador and.



<!ELEMENT not (not | and | or | instanceof | test | systemTest | equals | count | with | resolve | adapt | iterate)>

Este elemento representa uma operação NOT no resultado de avaliação da respectiva expressão de sub-elemento.



<!ELEMENT and (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>

Este elemento representa uma operação AND no resultado de avaliação de todas as respectivas expressões de subelemento.



<!ELEMENT or (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>

Este elemento representa uma operação OR no resultado de avaliação de todas as respectivas expressões de subelemento.



<!ELEMENT instanceof EMPTY>

<!ATTLIST instanceof

value CDATA #REQUIRED>

Este elemento é utilizado para desempenhar uma verificação instanceof do objecto em questão. A expressão devolve EvaluationResult.TRUE se o tipo do objecto for um subtipo do tipo especificado pelo valor do atributo. De outro modo, devolve EvaluationResult.FALSE.



<!ELEMENT test EMPTY>

<!ATTLIST test

property CDATA #REQUIRED

args     CDATA #IMPLIED

value    CDATA #IMPLIED>

Este elemento é utilizado para avaliar o estado de propriedade do objecto em questão. O conjunto de propriedades verificáveis pode ser alargado utilizando o ponto de extensão do dispositivo de testes de propriedade. A expressão do teste devolve EvaluationResult.NOT_LOADED se o dispositivo de testes de propriedade que está a fazer o teste ainda não estiver carregado.



<!ELEMENT systemTest EMPTY>

<!ATTLIST systemTest

property CDATA #REQUIRED

value    CDATA #REQUIRED>

Testa uma propriedade de sistema solicitando o método System.getProperty e compara o resultado com o valor especificado através do atributo value.



<!ELEMENT equals EMPTY>

<!ATTLIST equals

value CDATA #REQUIRED>

Este elemento é utilizado para desempenhar uma verificação equals do objecto em questão. A expressão devolve EvaluationResult.TRUE se o objecto for igual ao valor fornecido pelo atributo value. De outro modo, devolve EvaluationResult.FALSE.



<!ELEMENT count EMPTY>

<!ATTLIST count

value CDATA #REQUIRED>

Este elemento é utilizado para testar o número de elementos numa recolha.



<!ELEMENT with (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>

<!ATTLIST with

variable CDATA #REQUIRED>

Este elemento altera o objecto a ser inspeccionado em todos os elementos descendentes, para o objecto referenciado pela dada variável. Se a variável não puder ser processada, a expressão apresenta ExpressionException quando estiver a fazer a avaliação. Os elementos descendentes de uma expressão with são combinados com recurso ao operador and.



<!ELEMENT resolve (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>

<!ATTLIST resolve

variable CDATA #REQUIRED

args     CDATA #IMPLIED>

Este elemento altera o objecto a ser inspeccionado em todos os elementos descendentes, para o objecto referenciado pela dada variável. Se a variável não puder ser processada, a expressão apresenta ExpressionException quando estiver a fazer a avaliação. Os elementos descendentes de uma expressão with são combinados com recurso ao operador and.



<!ELEMENT adapt (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>

<!ATTLIST adapt

type CDATA #REQUIRED>

Este elemento é utilizado para adaptar o objecto em questão ao tipo especificado pelo tipo do atributo. A expressão devolve not loaded se o adaptador ou o tipo referenciados ainda não estiverem carregados. Apresenta ExpressionException durante a avaliação se o nome do tipo não existir. Os elementos descendentes de uma expressão adapt são combinados com recurso ao operador and.



<!ELEMENT iterate (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>

<!ATTLIST iterate

operator (or|and) >

Este elemento é utilizado para iterar numa variável que seja de tipo java.util.Collection. Se o objecto em questão não for do tipo java.util.Collection, surge ExpressionException durante a avaliação da expressão.



Uma definição básica de um menu tem esta aparência.

<menu id=

"com.mycompany.myplugin.projection"

label=

"%Folding.label"

>

<location mnemonic=

"%Folding.label.mnemonic"

>

<part id=

"AntEditor"

>

<popup id=

"#RulerContext"

path=

"rest"

/>

</part>

</location>

</menu>

Neste exemplo, o programador do plug-in contribui para todas as partes que coloquem em subclasses ou implementem o tipo determinado. Isto permite, por exemplo, que algumas contribuições sejam adicionadas a todos os editores de texto.

<menu id=

"com.mycompany.myplugin.textEditorMenu"

label=

"Text Commands"

>

<location mnemonic=

"X"

>

<part class=

"AbstractTextEditor"

>

<popup id=

"#RulerContext"

path=

"rest"

/>

</part>

</location>

</menu>

É possível associar a ajuda a um menu.

<menu id=

"com.mycompany.myplugin.RunWithConfigurationAction"

label=

"Run With Configuration"

helpContextId=

"run_with_configuration_context"

>

<location>

<bar />

</location>

</menu>

Num menu, é possível definir grupos lógicos. Estes grupos lógicos podem ser visíveis (como por exemplo, os separadores são retirados antes ou depois, conforme o modo adequado) ou invisível. Por predefinição, os grupos lógicos são visíveis.

<group id=

"com.mycompany.myplugin.stepGroup"

>

<location>

<bar path=

"org.eclipse.ui.run"

/>

</location>

</group>

<group id=

"com.mycompany.myplugin.stepIntoGroup"

separatorsVisible=

"false"

>

<location>

<bar path=

"org.eclipse.ui.run"

/>

</location>

</group>

É possível colocar menus, grupos, artigos e widgets em várias localizações.

<item id=

"com.mycompany.myplugin.ToggleStepFilters"

commandId=

"com.mycompany.myplugin.ToggleStepFilters"

>

<location mnemonic=

"%mnemonic"

>

<bar path=

"org.eclipse.ui.run/emptyStepGroup"

/>

</location>

<location>

<part id=

"org.eclipse.debug.ui.DebugView"

>

<bar type=

"trim"

path=

"renderGroup"

/>

</part>

</location>

<location mnemonic=

"%mnemonic"

>

<part id=

"org.eclipse.debug.ui.DebugView"

>

<popup path=

"renderGroup"

/>

</part>

</location>

</item>

Se o elemento emergente for especificado sem id e sem elemento de componente ascendente, é aplicado a qualquer menu contextual registado na área de trabalho. Este comportamento é semelhante ao comportamento das contribuições de objectos antigas. Do mesmo modo, um elemento emergente de nível superior com um id irá afectar qualquer menu contextual com o nome determinado.

<item id=

"com.mycompany.myplugin.ObjectContribution"

commandId=

"com.mycompany.myplugin.ObjectContribution"

>

<location>

<popup path=

"additions"

/>

</location>

</item>

Ocasionalmente, poderá pretender controlar a visibilidade de um artigo. Apesar de normalmente ser preferível manter a estabilidade na esquematização dos menus e das barras de ferramentas, por vezes é recomendado ocultar artigos que não são imediatamente relevantes. Esta situação ocorre particularmente nos menus contextuais, em que o espaço é limitado. Neste caso, é definido um elemento visibleWhen. Este elemento é muito semelhante aos elementos activeWhen e enabledWhen definidos no ponto de extensão da rotina de tratamento .

<item id=

"com.mycompany.myplugin.ConvertToWatchExpression"

commandId=

"com.mycompany.myplugin.ConvertToWatchExpression"

>

<location mnemonic=

"%mnemonic"

>

<part id=

"org.eclipse.debug.ui.DebugView"

>

<popup path=

"additions"

/>

</part>

</location>

<visibleWhen>

<with variable=

"selection"

>

<iterate operator=

"and"

>

<not>

<instanceof value=

"IWatchExpression"

/>

</not>

<instanceof value=

"IExpression"

/>

</iterate>

</with>

</visibleWhen>

</item>

O caso mais comum é apenas tornar algo visível quando a rotina de tratamento está activada. Este caso é processado com açúcar sintáctico. Existe um atributo checkEnabled no elemento visibleWhen.

<item id=

"com.mycompany.myplugin.compareWithPatch"

commandId=

"com.mycompany.myplugin.compareWithPatch"

>

<location mnemonic=

"%mnemonic"

>

<part id=

"MyPart"

>

<popup path=

"additions"

/>

</part>

</location>

<visibleWhen checkEnabled=

"true"

/>

</item>

Qualquer artigo associado a um comando pode incluir valores de parâmetros. Se o parâmetro de um determinado identificador não for definido, então há um erro. Se o artigo não contiver um comando, também há um erro.

<item id=

"com.mycompany.myplugin.RunHistory"

commandId=

"com.mycompany.myplugin.RunHistory"

>

<location>

<bar path=

"org.eclipse.ui.run"

/>

</location>

<parameter name=

"index"

value=

"1"

/>

</item>

É possível especificar a ordenação relativa. Esta especificação é feita através da utilização da ordenação do atributo no elemento de localização. O atributo de ordenação aceita os seguintes valores: start (coloca o elemento no início do contentor); end (coloca o elemento no fim do contentor); after (coloca o elemento depois do elemento equivalente, cujo id corresponde ref) e before (coloca o elemento antes do elemento equivalente, cujo id corresponde a ref). A ordem relativa pode ser aplicada a qualquer tipo de elemento do menu.

<item id=

"com.mycompany.myplugin.MyFirstItem"

commandId=

"com.mycompany.myplugin.MyFirstCommand"

>

<location>

<order position=

"start"

/>

<bar path=

"org.eclipse.ui.run"

/>

</location>

</item>

<item id=

"com.mycompany.myplugin.MySecondItem"

commandId=

"com.mycompany.myplugin.MySecondCommand"

>

<location>

<order position=

"after"

relativeTo=

"com.mycompany.myplugin.MyFirstItem"

/>

<bar path=

"org.eclipse.ui.run"

/>

</location>

</item>

Se requerer acesso directo aos widgets (como por exemplo, para compor uma caixa de combinação), poderá utilizar um elemento widget. Infelizmente, isto significa que se um elemento widget se tornar visível na interface do utilizador, haverá um carregamento do plug-in.

<widget id=

"com.mycompany.myplugin.MyComboBoxSimple"

class=

"com.mycompany.myplugin.MyComboBox"

>

<location>

<bar type=

"trim"

path=

"myGroup"

/>

</location>

</widget>

<widget id=

"com.mycompany.myplugin.MyComboBoxParameterized1"

class=

"com.mycompany.myplugin.MyComboBox:a,b,c"

>

<location>

<bar type=

"trim"

path=

"myGroup"

/>

</location>

</widget>

<widget id=

"com.mycompany.myplugin.MyComboBoxParameterized2"

>

<class class=

"com.mycompany.myplugin.MyComboBox"

>

<parameter name=

"list"

value=

"a,b,c"

/>

<parameter name=

"selected"

value=

"c"

/>

<parameter name=

"editable"

value=

"false"

/>

</class>

<location>

<bar type=

"trim"

path=

"myGroup"

/>

</location>

</widget>

Pode também utilizar widgets para contribuir para o ajuste da área de trabalho. O exemplo seguinte define um novo widget "HeapStatus" que deverá ser colocado, por predefinição, imediatamente após o ajuste da linha do estado (ou seja, no fundo da janela da área de trabalho). Para mais informações sobre os grupos predefinidos, consulte a descrição do elemento "bar".

Repare que o ajuste "groups" pode ser recolocados noutras áreas de ajuste. O relativeTo das informações sobre a localização irão pressupor que o grupo referido está na posição predefinida ao determinar a localização do novo ajuste. Geralmente, é esperado que os contribuintes deste tipo criem os seus próprios grupos para alojar um novo widget, permitindo que o elemento de ajuste seja recolocado independentemente dos outros elementos de ajuste. O grupo "status" é uma excepção importante.

   

<extension point=

"org.eclipse.ui.menus"

>

<group id=

"TestTrimAPI.heapStatusGroup"

separatorsVisible=

"true"

>

<location>

<bar type=

"trim"

/>

<order position=

"after"

relativeTo=

"status"

/>

</location>

</group>

<widget class=

"HeapStatusWidget"

id=

"TestTrimAPI.HeapStatus"

>

<location>

<bar path=

"heapStatusGroup"

type=

"trim"

/>

</location>

<layout fillMajor=

"false"

fillMinor=

"true"

/>

</widget>

</extension>

Para registar um menu contextual, utilize os métodos IWorkbenchPartSite.registerContextMenu.