Configuração do Visualizador Comum

org.eclipse.ui.navigator.viewer

3.2

O elemento viewer define a configuração para um visualizador comum. A extensão pode disponibilizar um id de menu emergente personalizado, sobrepor-se ao visualizador na questão de este disponibilizar ligação ao suporte de editor, disponibilizar um diálogo de filtro e/ou disponibilizar um diálogo "Available customizations". Além disso, os elementos de configuração imbricados proporcionam controlo total sobre a estrutura e comportamento do menu de contexto emergente.

O viewerContentBinding associa extensões content definidas (através do ponto de extensão navigatorContent) a visualizadores (definidos através do ponto de extensão org.eclipse.ui.views). Qualquer extensão content associada a um visualizador é descrita como visible. Um serviço de conteúdos (org.eclipse.ui.navigator.INavigatorContentService) não devolve extensões que não estejam visible para o respectivo id de visualizador.

<!ELEMENT extension (viewer* , viewerContentBinding* , viewerActionBinding* , dragAssistant)>

<!ATTLIST extension

point CDATA #REQUIRED

id    CDATA #IMPLIED

name  CDATA #IMPLIED>


<!ELEMENT viewer (popupMenu? , options?)>

<!ATTLIST viewer

viewerId    CDATA #REQUIRED

popupMenuId CDATA #IMPLIED>

Fornece configuração base para estabelecer as características de um visualizador. Os clientes têm igualmente de definir uma extensão org.eclipse.ui.views para criar o componente de visualização.



<!ELEMENT viewerContentBinding (includes? , excludes?)>

<!ATTLIST viewerContentBinding

viewerId CDATA #REQUIRED>

Os clientes têm de definir um ou mais elementos viwerContentBinding para descrever as extensões content e filtros comuns que estão visible para o visualizador. Uma extensão content ou filtro comum está visible se o id da extensão content ou do filtro comum corresponder a uma instrução includes num viewerContentBinding e não estiver excluída por uma instrução excludes. Se uma extensão content ou filtro comum não estiver visible para um visualizador, a extensão nunca vai receber pedidos de conteúdo por parte de um serviço de conteúdos ou ser apresentada ao utilizador no filtro de diálogos disponíveis.

Os clientes podem definir um elemento includes para seleccionar quais as extensões que estão visible para o visualizador e, de forma semelhante, um elemento excludes para extensões que não devem estar visible para o visualizador. Os clientes podem ainda definir as extensões que devem ser explicitamente consultadas para elementos raiz (através de ITreeContentProvider.getElements()) pelo atributo "isRoot". Se um ou mais elementos contentExtension tiverem a "isRoot" definida para true no âmbito da instrução includes, apenas essas extensões são consultadas para elementos raiz. O atributo "isRoot" não tem efeito para exclusões.

Um visualizador pode ter definidos múltiplos viewerContentBindings, sendo as respectivas instruções includes/excludes agregadas, para produzir o comportamento final.



<!ELEMENT viewerActionBinding (includes? , excludes?)>

<!ATTLIST viewerActionBinding

viewerId CDATA #REQUIRED>

Os clientes têm de definir quais os fornecedores de acções que estão visíveis para o respectivo visualizador. Os clientes podem definir um elemento includes para seleccionar quais as extensões que estão visible para o visualizador e, de forma semelhante, um elemento excludes para extensões que não devem estar visible para o visualizador.

Um visualizador pode ter definidos múltiplos viewerActionBindings, sendo as respectivas instruções includes/excludes agregadas, para produzir o comportamento final.

Para definições actionProvider que não estejam imbricadas numa definição navigatorContent, os clientes podem especificar um id personalizado. Se os clientes não especificarem um id, o id utiliza como predefinição "org.eclipse.ui.navigator.actionProvider.X". Os clientes que desejem escolher actionProviders sem id específico, têm de definir um viewerActionBinding para o id predefinido. Consulte a secção de exemplos para mais informações sobre a realização destas operações.



<!ELEMENT includes ((contentExtension+) | (actionExtension+))>

Definir um conjunto de padrões que devem ser incluídos ao procurar extensões content para o visualizador que corresponda ao atributo "viewerId". Quando as instruções includes e excludes se intersectam, a instrução includes tem precedência.



<!ELEMENT excludes ((contentExtension+) | (actionExtension+))>

Definir um conjunto de padrões que devem ser excluídos ao procurar extensões content para o visualizador que corresponda ao atributo "viewerId". Quando as instruções includes e excludes se intersectam, a instrução includes tem precedência.



<!ELEMENT contentExtension EMPTY>

<!ATTLIST contentExtension

pattern CDATA #REQUIRED

isRoot  (true | false) >

Indica o id (ou padrão correspondente) de uma extensão content que deve ser consultada por ITreeContentProvider.getElements() ou ITreeContentProvider.getChildren() para a raiz do visualizador ou um filtro comum que deve estar disponível para o utilizador no diálogo "Available Filters".

Os clientes podem especificar "isRoot" para seleccionar extensões raiz específicas para substituir as extensões que, de outro modo, estariam activas para o elemento de introdução de dados do visualizador (baseado na expressão triggerPoints correspondente para o elemento de introdução de dados do visualizador).

Consulte a documentação sobre viewerContentBinding para mais informações.



<!ELEMENT actionExtension EMPTY>

<!ATTLIST actionExtension

pattern CDATA #REQUIRED>

Indica a extensão de acção que deve ter oportunidades de contribuir para o contexto e barras de acções.

Consulte a documentação sobre viewerActionBinding para mais informações.



<!ELEMENT popupMenu (insertionPoint*)>

<!ATTLIST popupMenu

id                          CDATA #IMPLIED

allowsPlatformContributions (true | false) >

Um elemento emergente só pode ser definido se o atributo "popupMenuId" do elemento viewer não estiver especificado.

O elemento popupMenu permite a configuração adicional do menu de contexto associado ao visualizador. Para que as opções sejam aplicadas correctamente, tem de haver uma ocorrência do visualizador que delegue para um org.eclipse.ui.navigator.NavigatorActionService, que se comporta como um org.eclipse.ui.ActionGroup normal. Consulte a documentação para esta classe API para mais informações sobre a exploração desta funcionalidade. Clientes que utilizem uma ocorrência de org.eclipse.ui.navigator.CommonNavigator não necessitam de realizar qualquer tarefa adicional.

Um popupMenu declara um ou mais insertionPoints que são utilizados pelos contribuintes para organizar as respectivas contribuições numa lista compreensível, fácil de utilizar e consistente.
Se os clientes especificarem apenas o atributo "popupMenuId" do elemento viewer, o conjunto de insertionPoints utilizado pelo menu de contexto é predefinido para a seguinte lista na ordem dada:

"group.new"             separator="true"
"group.goto"            
"group.open"            separator="true"
"group.openWith"
"group.show"            separator="true"
"group.edit"            separator="true"
"group.reorganize"
"group.port"
"group.generate"        separator="true"
"group.search"          separator="true"
"group.build"           separator="true"
"additions"             separator="true" 
"group.properties"      separator="true"


Os clientes que queiram referir-se programaticamente a estes valores podem utilizar as constantes correspondentes em org.eclipse.ui.navigator.ICommonMenuConstants.

Os clientes que queiram personalizar os respectivos menus são incentivados a começar por esta lista, adicionando ou removendo pontos de inserção como necessário. Os clientes são igualmente incentivados a seguir o padrão de começar o nome de cada grupo por "group".

Se o elemento popupMenu estiver especificado e NÃO contiver elementos descendentes insertionPoint, o menu de contexto não terá pontos de inserção publicados. Evidentemente, os clientes programáticos não estão restringidos de adicionar os seus próprios pontos de inserção como necessário. Os clientes que definam visualizadores são incentivados a publicar os respectivos pontos de inserção, para efeitos de documentação e clareza das extensões em sentido descendente, para os respectivos visualizadores/navegadores, ou para documentar explicitamente quais os pontos de inserção que são considerados API e quais são considerados internos.



<!ELEMENT insertionPoint EMPTY>

<!ATTLIST insertionPoint

name      CDATA #REQUIRED

separator (true | false) >

Define um ponto de inserção para o menu de contexto. Inclui o nome do ponto para referência dos clientes, bem como se o ponto de inserção deve ser apresentado como um separador ou marcador de grupo.



<!ELEMENT options (property+)>

Disponibiliza opções ao visualizador para personalizar a forma como é apresentado ao utilizador. Consulte org.eclipse.ui.navigator.INavigatorViewerDescriptor para informações relativas às propriedades disponíveis.



<!ELEMENT property EMPTY>

<!ATTLIST property

name  CDATA #REQUIRED

value CDATA #REQUIRED>

Fornecer um par nome=valor. O valor é fornecido ao visualizador tal como está (de modo a que as cadeias vazias sejam propagadas como cadeias vazias). Consulte org.eclipse.ui.navigator.INavigatorViewerDescriptor para informações relativas às propriedades disponíveis e respectivas descrições.



<!ELEMENT dragAssistant EMPTY>

<!ATTLIST dragAssistant

class    CDATA #REQUIRED

viewerId CDATA #REQUIRED>

Um assistente de Arrastar e Largar disponibiliza uma rotina flexível para fornecer tipos de transferência suplementares, bem como lógica para definir os dados a arrastar. Este elemento não é requerido, uma vez que o org.eclipse.ui.navigator.CommonViewer básico disponibiliza um tipo org.eclipse.jface.util.LocalSelectionTransfer.

Os clientes devem definir esta extensão exclusivamente em plug-ins flexíveis com árvores de dependência pouco ramificadas. Os assistentes de arrastar têm de ser imediatamente carregados quando o visualizador é criado, o que obriga a carregar os plugins afectados.



O exemplo seguinte configura o id de menu emergente para um visualizador.


   

<extension point=

"org.eclipse.ui.navigator.viewer"

>

<viewer id=

"org.eclipse.testViewer"

popupMenuId=

"org.eclipse.testViewer#PopupMenu"

/>

</extension>

Dado que o elemento descendente popupMenu do visualizador não é utilizado no exemplo acima, é utilizado o conjunto insertionPoints predefinido. Este conjunto está definido da seguinte forma. Consulte a documentação relativa ao elemento popupMenu para mais informações.

"group.new"             separator="true"
"group.goto"            
"group.open"            separator="true"
"group.openWith"
"group.show"            separator="true"
"group.edit"            separator="true"
"group.reorganize"
"group.port"
"group.generate"        separator="true"
"group.search"          separator="true"
"group.build"           separator="true"
"additions"             separator="true" 
"group.properties"      separator="true"

O exemplo seguinte demonstra uma configuração de visualizador que declara popupMenu/insertionPoints personalizados, mas restringe contribuições de objecto e visualizador com o atributo "allowsPlatformContributions". Os clientes podem contribuir para o menu definido exclusivamente através de org.eclipse.ui.navigator.CommonActionProviders declarados para o visualizador (ou de nível superior ou associado a extensões content).

Note que o atributo "popupMenuId" não é especificado concorrentemente com o elemento popupMenu. Apenas um ou outro, mas não ambos, representa uma configuração válida.

   

<extension point=

"org.eclipse.ui.navigator.viewer"

>

<viewer viewerId=

"org.eclipse.ui.navigator.resourceContent"

>

<popupMenu allowsPlatformContributions=

"false"

id=

"org.eclipse.ui.navigator.resourceContent#PopupMenu"

>

<insertionPoint name=

"group.new"

/>

<insertionPoint name=

"group.open"

separator=

"true"

/>

<insertionPoint name=

"group.openWith"

/>

<insertionPoint name=

"group.port"

separator=

"true"

/>

<insertionPoint name=

"additions"

separator=

"true"

/>

<insertionPoint name=

"group.properties"

separator=

"true"

/>

</popupMenu>

</viewer>

<viewerContentBinding viewerId=

"org.eclipse.ui.navigator.resourceContent"

>

<includes>

<contentExtension pattern=

"org.eclipse.ui.navigator.resourceContent"

/>

</includes>

</viewerContentBinding>

</extension>

O exemplo seguinte declara que uma extensão content (id: "org.eclipse.ui.navigator.resourceContent") está associada a um visualizador correspondente ao id "org.eclipse.ui.navigator.resourceContent". (Neste exemplo, os ids da extensão content e do visualizador são correspondentes, mas tal não é requerido.) Além disso, qualquer extensão content com um id que comece por "org.eclipse.ui.navigator.tests." é ignorada.

   

<extension point=

"org.eclipse.ui.navigator.viewer"

>

<viewerContentBinding viewerId=

"org.eclipse.ui.navigator.resourceContent"

>

<includes>

<contentExtension pattern=

"org.eclipse.ui.navigator.resourceContent"

/>

</includes>

<excludes>

<contentExtension pattern=

"org.eclipse.ui.navigator.tests.*"

/>

</excludes>

</viewerContentBinding>

</extension>

O exemplo seguinte declara uma viewerActionBinding para todos os actionProviders (não imbricados numa extensão navigatorContent) que correspondam à expressão global "org.acme.actions.*" mas não "org.acme.actions.tests.*". Esta expressão faz com que qualquer actionProvider cujo id comece por "org.acme.actions." mas não por "org.acme.actions.tests." fique visible para o visualizador com o id "org.acme.viewer". Evidentemente, as viewerActionBindings aplicam-se exclusivamente a elementos actionProvider que não estejam imbricados num elemento navigatorContent. A visibility de elementos actionProvider imbricados é controlada por viewerContentBindings para o elemento navigatorContent delimitador.

   

<extension point=

"org.eclipse.ui.navigator.viewer"

>

<viewerActionBinding viewerId=

"org.acme.viewer"

>

<includes>

<actionExtension pattern=

"org.acme.actions.*"

/>

</includes>

<excludes>

<actionExtension pattern=

"org.acme.actions.tests.*"

/>

</excludes>

</viewerActionBinding>

</extension>

O exemplo seguinte faz com que qualquer actionProvider sem atributo "id" fique visible para o visualizador "org.acme.viewer". Os actionProviders sem atributo "id" têm o id predefinido "org.eclipse.ui.navigator.actionProvider.X". Evidentemente, as viewerActionBindings aplicam-se exclusivamente a elementos actionProvider que não estejam imbricados num elemento navigatorContent. A visibility de elementos actionProvider imbricados é controlada por viewerContentBindings para o elemento navigatorContent delimitador.

   

<extension point=

"org.eclipse.ui.navigator.viewer"

>

<viewerActionBinding viewerId=

"org.acme.viewer"

>

<includes>

<actionExtension pattern=

"org.eclipse.ui.navigator.actionProvider.*"

/>

</includes>

</viewerActionBinding>

</extension>

O exemplo seguinte demonstra as propriedades padrão disponíveis para o visualizador.

   

<extension point=

"org.eclipse.ui.navigator.viewer"

>

<viewer popupMenuId=

"org.eclipse.ui.tests.navigator.TestView#PopupMenu"

viewerId=

"org.eclipse.ui.tests.navigator.TestView"

>

<options>

<!-- Hide the

"Available Extensions"

tab in the

"Available Customizations"

dialog (available from the

"Filters"

action -->

<property name=

"org.eclipse.ui.navigator.hideAvailableExtensionsTab"

value=

"true"

/>

<!-- Hide the

"Available Customizations"

dialog completely. This includes hiding the filters and the available content extensions. -->

<property name=

"org.eclipse.ui.navigator.hideAvailableCustomizationsDialog"

value=

"true"

/>

<!-- Hide the

"Link with Editor"

action from the toolbar of the viewer -->

<property name=

"org.eclipse.ui.navigator.hideLinkWithEditorAction"

value=

"true"

/>

<!-- Hide the

"Collapse All"

action from the toolbar of the viewer -->

<property name=

"org.eclipse.ui.navigator.hideCollapseAllAction"

value=

"true"

/>

</options>

</viewer>

</extension>