Configuración de visor común

org.eclipse.ui.navigator.viewer

3.2

El elemento viewer define la configuración para un visor común. La extensión puede proporcionar un ID de menú emergente personalizado, alterar temporalmente si el visor proporciona un enlace con el soporte del editor, proporciona un diálogo de filtro y/o proporciona un diálogo "Personalizaciones disponibles". Además, los elementos de configuración anidados proporcionan un control total sobre la estructura y el comportamiento del menú de contexto emergente.

Los enlaces de viewerContentBinding enlaza extensiones de contenido definidas (a través del punto de extensión navigatorContent) con visores (definidos a través del punto de extensión org.eclipse.ui.views.) Cualquier extensión de contenido enlazada a un visor se describe como visible. Un servicio de contenido (org.eclipse.ui.navigator.INavigatorContentService) no devolverá ninguna extensión que no sea visible para el ID del visor correspondiente.

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

Proporciona una configuración básica para establecer las características de un visor. Los clientes también deben definir una extensión org.eclipse.ui.views para crear el componente de la vista.



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

<!ATTLIST viewerContentBinding

viewerId CDATA #REQUIRED>

Los clientes deben definir uno o varios elementos viwerContentBinding para que describan qué extensiones de contenido y que filtros son visibles para el visor. Una extensión de contenido o un filtro común es visible si el ID de la extensión de contenido o el filtro común coincide con una sentencia includes bajo un viewerContentBinding y no está excluido por una sentencia excludes. Si una extensión de contenido o un filtro común no es visible para un visor, ningún servicio de contenido del visor solicitará contenido de la extensión ni tampoco se presentará ésta al usuario en el diálogo de filtros disponibles.

Los clientes pueden definir un elemento includes para seleccionar qué extensiones son visibles para el visor y también un elemento excludes para las extensiones que no deban ser visibles para el visor. Los clientes pueden definir las extensiones cuyos elementos raíz deben consultarse explícitamente (a través de ITreeContentProvider.getElements()) mediante el atributo "isRoot". Si uno o varios elementos contentExtension tienen "isRoot" establecido en true con la sentencia includes, solo se consultarán esas en busca de elementos raíz. El atributo "isRoot" no tiene efecto para las exclusiones.

Un visor puede tener varios viewerContentBindings definidos y sus sentencias includes/excludes se agregarán para generar el comportamiento final.



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

<!ATTLIST viewerActionBinding

viewerId CDATA #REQUIRED>

Los clientes deben definir qué proveedores de acción son visibles para su visor. Los clientes pueden definir un elemento includes para seleccionar qué extensiones son visibles para el visor y también un elemento excludes para las extensiones que no deban ser visibles para el visor.

Un visor puede tener varios viewerContentBinding definidos y sus sentencias includes/excludes se agregarán para generar el comportamiento final.

Para las definiciones de actionProvider que no están anidadas bajo una definición de navigatorContent, los clientes pueden especificar un ID personalizado. Si los clientes no especifican un ID, el valor predeterminado del ID es "org.eclipse.ui.navigator.actionProvider.X". Los clientes que deseen recoger los actionProvider sin ID específico deben definir un viewerActionBinding para el ID predeterminado. Consulte la sección de ejemplos para saber cómo hacer esto.



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

Definir un conjunto de patrones que deben incluirse al buscar extensiones de contenido para el visor que coincide con el atributo "viewerId". Cuando las sentencias includes y excludes se cruzan, la sentencia includes tiene preferencia.



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

Definir un conjunto de patrones que deben excluirse al buscar extensiones de contenido para el visor que coincide con el atributo "viewerId". Cuando las sentencias includes y excludes se cruzan, la sentencia includes tiene preferencia.



<!ELEMENT contentExtension EMPTY>

<!ATTLIST contentExtension

pattern CDATA #REQUIRED

isRoot  (true | false) >

Indica el ID (o el patrón coincidente) de una extensión de contenido que ITreeContentProvider.getElements() o ITreeContentProvider.getChildren() debe consultar en busca de la raíz del visor o un filtro común que debe estar disponible para el usuario en el diálogo "Filtros disponibles".

Los clientes pueden especificar "isRoot" para seleccionar extensiones raíz específicas para alterar temporalmente las extensiones que de otra manera estarían habilitadas para el elemento de entrada del visor (basado en la expresión triggerPoints coincidente para el elemento de entrada del visor.)

Consulte la documentación de viewerContentBinding para obtener más información.



<!ELEMENT actionExtension EMPTY>

<!ATTLIST actionExtension

pattern CDATA #REQUIRED>

Indica la extensión de acción que debe tener la oportunidad de contribuir al menú de contexto y las barras de acciones.

Consulte la documentación de viewerActionBinding para obtener más información.



<!ELEMENT popupMenu (insertionPoint*)>

<!ATTLIST popupMenu

id                          CDATA #IMPLIED

allowsPlatformContributions (true | false) >

Un elemento popupMenu solo se puede definir si no se especifica el atributo "popupMenuId" del elemento viewer.

El elemento popupMenu permite una mayor personalización del menú de contexto asociado al visor. Para aplicar correctamente las opciones, una instancia del visor debe delegar en un org.eclipse.ui.navigator.NavigatorActionService que se comporta como un org.eclipse.ui.ActionGroup normal. Consulte la documentación de esta clase de API para obtener más información acerca de cómo aprovechar esta funcionalidad. Los clientes que utilizan una instancia de org.eclipse.ui.navigator.CommonNavigator no necesitan llevar a cabo ninguna acción adicional.

Un popupMenu declara uno o varios insertionPoints que utilizarán los contribuyentes para organizar sus contribuciones en una lista significativa, coherente y de fácil comprensión.
Si los clientes solo especifican el atributo "popupMenuId" del elemento viewer, el conjunto de insertionPoints utilizado por el menú de contexto será por omisión la lista siguiente por este orden:

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


Los clientes que deseen hacer referencia a estos valores programáticamente, podrán utilizar las constantes correspondientes en org.eclipse.ui.navigator.ICommonMenuConstants.

Para los clientes que deseen personalizar sus menús es recomendable que empiecen por esta lista y añadan o eliminen puntos de inserción según sea necesario. Los clientes también deben seguir el patrón de empezar cada nombre de grupo por "group.".

Si el elemento popupMenu se especifica y no contiene elementos hijo de insertionPoint, el menú de contexto no tendrá puntos de inserción publicados. Por supuesto, los clientes programáticos pueden añadir sus propios puntos de inserción según sea necesario. Los clientes que definen los visores pueden publicar sus puntos de inserción a efectos de documentación y clarificación de las extensiones en sentido descendente en sus visores/navegadores o para documentar explícitamente qué puntos de inserción se consideran API y cuáles se consideran internos.



<!ELEMENT insertionPoint EMPTY>

<!ATTLIST insertionPoint

name      CDATA #REQUIRED

separator (true | false) >

Define un punto de inserción para el menú de contexto. Incluye el nombre del punto al que se hacen referencia los clientes y si el punto de inserción debe representarse como un separador de un marcador de grupo.



<!ELEMENT options (property+)>

Proporcionar opciones al visor para personalizar la presentación al usuario. Consulte org.eclipse.ui.navigator.INavigatorViewerDescriptor para conocer las propiedades disponibles.



<!ELEMENT property EMPTY>

<!ATTLIST property

name  CDATA #REQUIRED

value CDATA #REQUIRED>

Proporcionar un par nombre=valor. El valor se proporcionará tal cual al visor (así, las series vacías se propagarán como series vacías.) Consulte org.eclipse.ui.navigator.INavigatorViewerDescriptor para conocer las propiedades disponibles y sus descripciones.



<!ELEMENT dragAssistant EMPTY>

<!ATTLIST dragAssistant

class    CDATA #REQUIRED

viewerId CDATA #REQUIRED>

Un asistente de arrastrar y soltar proporciona un gancho ligero para proporcionar tipos de transferencia adicionales y lógica para establecer los datos de arrastre. Este elemento no es necesario ya que el org.eclipse.ui.navigator.CommonViewer básico proporciona un tipo org.eclipse.jface.util.LocalSelectionTransfer.

Los clientes solo deben definir esta extensión en plug-ins ligeros con árboles de dependencia poco profundos. Los asistentes de arrastre deben cargarse primero cuando se crea el visor, lo que forzará la carga de los plug-ins afectados.



En el ejemplo siguiente se configura el ID de menú emergente para un visor.


   

<extension point=

"org.eclipse.ui.navigator.viewer"

>

<viewer id=

"org.eclipse.testViewer"

popupMenuId=

"org.eclipse.testViewer#PopupMenu"

/>

</extension>

Puesto que el elemento hijo popupMenu del visor no se utiliza en el ejemplo anterior, se utilizará el conjunto predeterminado de insertionPoints. Este conjunto se define de la manera siguiente. Consulte la documentación del elemento popupMenu para obtener más información.

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

En el ejemplo siguiente se muestra una configuración de visor que declara popupMenu/insertionPoints pero que restringe contribuciones de objeto y de visor con el atributo "allowsPlatformContributions". Los clientes solo pueden contribuir al menú definido a través de los org.eclipse.ui.navigator.CommonActionProvider declarados para el visor (ya sea de nivel superior o asociados a extensiones de contenido.)

Tenga en cuenta que el atributo "popupMenuId" no se especifica actualmente con el elemento popupMenu. Solo uno u otro, pero no ambos, constituyen una configuración 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>

En el ejemplo siguiente se declara que una extensión de contenido (id: "org.eclipse.ui.navigator.resourceContent") está enlazada a un visor que coincide con el ID "org.eclipse.ui.navigator.resourceContent". (En este ejemplo los ID de la extensión de contenido y el visor coinciden, pero esto no es necesario.) Más aún, se omitirá cualquier extensión de contenido con un ID que empiece por "org.eclipse.ui.navigator.tests.".

   

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

En el ejemplo siguiente se declara un viewerActionBinding para todos los actionProvider (no anidados bajo una extensión navigatorContent) que coincidan con la expresión regular "org.acme.actions.*" pero no con "org.acme.actions.tests.*". Esta expresión hará visible para el visor cualquier actionProvider cuyo id empiece por "org.acme.actions." pero no por "org.acme.actions.tests.", con el ID "org.acme.viewer". Por supuesto, viewerActionBindings solo se aplica a los elementos actionProvider que no están anidados bajo un elemento navigatorContent. La visibilidad de los elementos actionProvider está controlada por viewerContentBindings para el 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>

En el ejemplo siguiente, cualquier actionProvider sin atributo "id" se hace visible para el visor "org.acme.viewer". Los actionProvider sin atributo "id" tienen el ID predeterminado "org.eclipse.ui.navigator.actionProvider.X". Por supuesto, viewerActionBindings solo se aplica a los elementos actionProvider que no están anidados bajo un elemento navigatorContent. La visibilidad de los elementos actionProvider anidados está controlada por los viewerContentBinding para el 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>

En el ejemplo siguiente se muestran las propiedades estándar disponibles para el visor.

   

<extension point=

"org.eclipse.ui.navigator.viewer"

>

<viewer popupMenuId=

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

viewerId=

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

>

<options>

<!-- Ocultar la pestaña

"Extensiones disponibles"

en el diálogo

"Personalizaciones disponibles"

(disponible desde la acción

"Filtros"

-->

<property name=

"org.eclipse.ui.navigator.hideAvailableExtensionsTab"

value=

"true"

/>

<!-- Ocultar el diálogo

"Personalizaciones disponibles"

completamente. Esto incluye ocultar los filtros y las extensiones de contenido disponibles. -->

<property name=

"org.eclipse.ui.navigator.hideAvailableCustomizationsDialog"

value=

"true"

/>

<!-- Ocultar la acción

"Enlazar con editor"

de la barra de herramientas del visor -->

<property name=

"org.eclipse.ui.navigator.hideLinkWithEditorAction"

value=

"true"

/>

<!-- Ocultar la acción

"Contraer todo"

de la barra de herramientas del visor -->

<property name=

"org.eclipse.ui.navigator.hideCollapseAllAction"

value=

"true"

/>

</options>

</viewer>

</extension>