Visores de código fuente y anotaciones

La infraestructura de texto de la plataforma proporciona clases de interfaz de usuario que implementan una variada presentación del documento de un editor.   

El editor y su visor de texto correspondiente son en gran medida responsables de la implementación de la presentación y configuración del documento de las clases de ayuda necesarias.  (Consulte la sección Visores si no está familiarizado con el concepto de visor).  

Un TextViewer (visor de texto) maneja todos los detalles de bajo nivel de la correlación entre el modelo de documento y sus particiones y el texto coloreado y formateado que el usuario visualiza.  Para los editores de estilo de código fuente, se suministra un SourceViewer (visor de código fuente).  El visor de código fuente introduce el concepto de anotaciones de código fuente.  Estas anotaciones pueden mostrarse en una regla vertical a la izquierda del texto, en una regla de visión general a la derecha del texto, o como marcas coloreadas debajo del texto.

SourceViewer y sus clases de ayuda se utilizan en toda la jerarquía de AbstractTextEditor.   El paquete org.eclipse.jface.text.source define este visor y las demás clases que dan soporte a la presentación de anotaciones.

Anotaciones y reglas

Hemos visto anteriormente que un proveedor de documentos suministra un modelo para las anotaciones de su documento, IAnnotationModel, además del documento propiamente dicho.  Este modelo de anotaciones contiene las anotaciones, las enumera bajo demanda y está a la escucha de los cambios de texto a fin de mantener las anotaciones actualizadas con respecto al texto.  JavaDocumentProvider hereda el comportamiento definido en FileDocumentProvider y, por tanto, su modelo de anotación.

protected IAnnotationModel createAnnotationModel(Object element) throws CoreException {
	if (element instanceof IFileEditorInput) {
		IFileEditorInput input= (IFileEditorInput) element;
		return new ResourceMarkerAnnotationModel(input.getFile());
	}
	return super.createAnnotationModel(element);
}

ResourceMarkerAnnotationModel define un modelo de anotaciones que representa un marcador en un recurso del entorno de trabajo.  (Consulte la sección Marcadores de recursos para obtener más información acerca de los marcadores).  Asigna una imagen y una descripción a cada marcador y supervisa su recurso para registrar los cambios efectuados en los marcadores.

Para saber cómo se visualiza un modelo de anotación en un editor de texto, examinaremos el editor de texto de la plataforma y su utilización de reglas y anotaciones.  El usuario puede controlar los detalles específicos relativos a cómo se muestran las diversas anotaciones en las reglas y el texto mediante las preferencias Entorno de trabajo > Editores > Editor de texto de la pestaña Anotaciones.

Regla vertical

Los editores de texto de la plataforma utilizan una regla vertical situada a la izquierda del área de edición para mostrar rangos de texto y anotaciones basadas en línea adyacentes a la línea de texto.

Estas anotaciones se describen en el ResourceMarkerAnnotationModel que se suministra.  Este modelo se define en el SourceViewer cuando el editor inicializa el visor de código fuente.  El siguiente fragmento de código de AbstractTextEditor muestra la forma en que el modelo de documento y de anotaciones se asocia con el visor.

private void initializeSourceViewer(IEditorInput input) {
		
	IAnnotationModel model= getDocumentProvider().getAnnotationModel(input);
	IDocument document= getDocumentProvider().getDocument(input);
		
	if (document != null) {
		fSourceViewer.setDocument(document, model);
		...

Una vez que el visor de código fuente está configurado con el modelo de documento y de anotaciones adecuado, ya dispone de información suficiente para presentar el documento y garantizar que se muestren las anotaciones correctas en la regla vertical de la izquierda.  El modelo se asocia con la regla cuando se define el documento.  El fragmento de código que figura a continuación muestra lo que ocurre cuando se define un documento en el visor de código fuente.  Se ha simplificado a partir del código real que figura en SourceViewer a efectos de claridad:

public void setDocument(IDocument document, IAnnotationModel annotationModel) {
	...
	// crear modelo de anotación visual a partir del modelo suministrado y
	// almacenarlo en fVisualAnnotationModel
	...
	if (fVerticalRuler != null)
		fVerticalRuler.setModel(fVisualAnnotationModel);

De este modo, la regla se asocia con el modelo de anotación adecuado.  

Observemos la regla propiamente dicha.  La crea el editor de texto y, a continuación, se conecta con el visor del editor.  Dado que el ejemplo de editor Java no define ningún comportamiento especial para las reglas, hereda la regla definida en TextEditor.

protected IVerticalRuler createVerticalRuler() {
	CompositeRuler ruler= new CompositeRuler();
	ruler.addDecorator(0, new AnnotationRulerColumn(VERTICAL_RULER_WIDTH));
	if (isLineNumberRulerVisible())
		ruler.addDecorator(1, createLineNumberRulerColumn());
	return ruler;
}

El editor de texto utiliza una CompositeRuler. Esta regla no tiene una presentación visual propia.  La presentación se obtiene mediante una lista de decoradores que muestran columnas (IVerticalRulerColumn) en la regla.  En este ejemplo, siempre se añade a la regla una columna que muestra anotaciones (AnnotationRulerColumn) y, en función de las preferencias del usuario, se añade a la regla una columna de número de línea. La columna de anotaciones de la regla maneja las particularidades de la visualización de las imágenes de anotación en las ubicaciones adecuadas.

A pesar de todas las clases implicadas en la visualización de la regla, observe que el editor de ejemplo sólo necesita crear subclases de las clases de infraestructura para obtener el comportamiento de la regla.   JavaDocumentProvider hereda un modelo de anotación de marcadores adecuado de FileDocumentProvider.   El JavaTextEditor hereda la presentación de la regla de TextEditor.

Regla de visión general

La regla de visión general situada a la derecha del área de edición se utiliza para mostrar las anotaciones que conciernen a todo el documento.  Estas anotaciones se muestran en relación a su posición en el documento y no se mueven cuando el usuario se desplaza por el mismo.  Generalmente, existe una anotación correspondiente en la regla vertical cuando esa parte del documento es visible.  

La regla vertical que figura a continuación muestra que en el documento existen dos tareas y una marca en el texto.  Puesto que el texto marcado es visible, su anotación también aparece a la izquierda.

Regla vertical del editor Java

El usuario puede desplazarse hasta la ubicación de la anotación en el código pulsando sobre la anotación.

Los tipos de anotaciones que se muestran en la regla de visión general se determinan añadiendo tipos de anotaciones a la regla.  En el siguiente fragmento de código de SourceViewerDecorationSupport, los tipos de anotaciones se añaden dinámicamente a la regla. (Consulte la próxima sección para obtener más información acerca de SourceViewerDecorationSupport).

private void showAnnotationOverview(Object annotationType) {
if (fOverviewRuler != null) { Color c= getAnnotationTypeColor(annotationType);
fOverviewRuler.setAnnotationTypeColor(annotationType, c); int l= getAnnotationTypeLayer(annotationType);
fOverviewRuler.setAnnotationTypeLayer(annotationType, l);
fOverviewRuler.addAnnotationType(annotationType);
fOverviewRuler.update();
} }

La regla de visión general también se suministra con un IAnnotationAccess que se utiliza para proporcionar información acerca de una anotación en particular, como por ejemplo su tipo y cómo se visualiza.  El TextEditor utiliza un DefaultMarkerAnnotationAccess que interpreta las anotaciones de acuerdo con sus tipos de marcadores y consulta las preferencias del usuario para saber qué tipos de marcadores deben mostrarse en la regla de visión general.

protected IAnnotationAccess createAnnotationAccess() {
	return new DefaultMarkerAnnotationAccess(fAnnotationPreferences);
}

Consulte la implementación de DefaultMarkerAnnotationAccess y MarkerAnnotation para conocer más detalles acerca de la presentación de marcadores en la regla de visión general.

Anotaciones de texto

Además de mostrar anotaciones en las reglas, un visor de código fuente puede mostrar anotaciones en forma de marcas coloreadas en el texto.  

Marca de texto en el editor Java

Observaremos de nuevo la creación del visor de código fuente en TextEditor.

protected ISourceViewer createSourceViewer(Composite parent, IVerticalRuler ruler, int styles) {
		
	... 
	ISourceViewer sourceViewer= new SourceViewer(parent, ruler, fOverviewRuler, isOverviewRulerVisible(), styles);
	fSourceViewerDecorationSupport= new SourceViewerDecorationSupport(sourceViewer, fOverviewRuler, fAnnotationAccess, sharedColors);
	configureSourceViewerDecorationSupport();
		
	return sourceViewer;
}

La clase SourceViewerDecorationSupport maneja muchas de las decoraciones que aparecen en un visor de código fuente, incluyendo las anotaciones de texto, márgenes coloreados, líneas de cursor coloreadas, etc.  Está configurada con las preferencias del usuario, de forma que puede responder a las actualizaciones dinámicas de los cambios de preferencias del usuario.  La mayoría de los editores no necesitan preocuparse por los detalles de representación de estas decoraciones.  (Consulte SourceViewerDecorationSupport y las clases relacionadas, como por ejemplo AnnotationPainter, si es necesario).  Lo que es importante conocer son las decoraciones que están disponibles, para que el SourceViewer y el SourceViewerDecorationSupport que le da soporte se configuren correctamente.

Configurar un SourceViewerDecorationSupport

Observemos la configuración utilizada por TextEditor para el soporte de decoración.

protected void configureSourceViewerDecorationSupport() {

	Iterator e= fAnnotationPreferences.getAnnotationPreferences().iterator();
	while (e.hasNext())
		fSourceViewerDecorationSupport.setAnnotationPreference((AnnotationPreference) e.next());
	fSourceViewerDecorationSupport.setAnnotationPainterPreferenceKeys(DefaultMarkerAnnotationAccess.UNKNOWN, UNKNOWN_INDICATION_COLOR, UNKNOWN_INDICATION, UNKNOWN_INDICATION_IN_OVERVIEW_RULER, 0);
		
	fSourceViewerDecorationSupport.setCursorLinePainterPreferenceKeys(CURRENT_LINE, CURRENT_LINE_COLOR);
	fSourceViewerDecorationSupport.setMarginPainterPreferenceKeys(PRINT_MARGIN, PRINT_MARGIN_COLOR, PRINT_MARGIN_COLUMN);
	fSourceViewerDecorationSupport.setSymbolicFontName(getFontPropertyPreferenceKey());
}

Observe que las preferencias de anotación se utilizan para definir tipos de anotación para todas las anotaciones que aparecen en las preferencias de usuario.  Esto incluye las anotaciones aportadas por cualquier conector, y no se limita a las anotaciones suministradas por el entorno de trabajo.  Si no desea mostrar todas las anotaciones disponibles en el editor, debe alterar temporalmente este método y configurar el SourceViewerDecorationSupport sólo con aquellos tipos que desee mostrar.

Copyright IBM Corporation y otros 2000, 2003.