Visualizações de origem e anotações

O editor e o seu visualizador de texto correspondente são grandemente responsáveis pela implementação da apresentação do documento e pela configuração das classes ajudantes necessárias.   (Consulte Visualizadores se não conhecer o conceito de visualizador.)   

Um TextViewer trata todos os detalhes menores da correlação de um modelo de documentos e respectivas partições com o texto colorido e formatado que é visível para o utilizador.  Para editores de estilo de código fonte, é facultado um SourceViewer.  Um visualizador de fonte introduz a noção de anotações de código fonte.  Estas anotações podem ser apresentadas numa régua vertical do lado esquerdo do texto, uma régua de descrição geral à dirita do texto, ou como #squigglies coloridos debaixo do texto.

O SourceViewer e as respectivas classes ajudantes são utilizados em toda a hierarquia AbstractTextEditor.  O pacote org.eclipse.jface.text.source define este visualizador e as outras classes que suportam a apresentação de anotações.

Anotações e réguas

As anotações, tal como as partições, dependem grandemente do tipo de documento em edição. O IAnnotationModel para um documento é o que mantém as anotações, as enumera a pedido e aguarda por/escuta alterações de texto para manter as anotações actualizadas com o texto. Os modelos de anotações são registados na extensão org.eclipse.core.filebuffers.annotationModelCreation. Este ponto de extensão permite aos plug-ins registarem uma classe que venha a criar um modelo de anotações apropriado para determinada extensão de ficheiro. O exemplo de editor Java não utiliza este ponto de extensão e por isso herda o modelo de anotações definido pela plataforma.

<extension
	point="org.eclipse.core.filebuffers.annotationModelCreation">
	<factory
		extensions="*"
		class="org.eclipse.ui.texteditor.ResourceMarkerAnnotationModelFactory">
	</factory>
</extension>

A classe de fábrica fornecida irá criar um ResourceMarkerAnnotationModel para ficheiros com qualquer estensão. Esta classe apresenta anotações que representam um marcador num recurso existente no espaço de trabalho.   (Consulte Marcadores de recursos para mais informações sobre marcadores.)  Atribui uma imagem e descrição a cada marcador e supervisiona o respectivo recurso em caso de alterações aos marcadores.

Para ver como um modelo de anotações é apresentado num editor de texto, iremos examinar o editor de texto da plataforma e a sua utilização de réguas e anotações.  As especificidades da apresentação de anotações em réguas e texto podem ser controladas pelo utilizador nas preferências Geral > Editores > Editores de Texto > Anotações.

Régua vertical

Uma régua vertical à esquerda da área de edição é utilizada pelos editores de texto da plataforma para mostrar intervalos de texto e anotações baseadas em linhas adjacentes à respectiva linha de texto.

Régua vertical

Estas anotações estão descritas no ResourceMarkerAnnotationModel fornecido.   Este modelo está definido no SourceViewer quando o visualizador de fonte for iniciado pelo editor.  A porção de código seguinte do AbstractTextEditor mostra como os modelos de documentos e anotações estão associados ao visualizador.

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

Uma vez o visualizador de fonte configurado com o modelo de documentos e anotações correcto, dispõe de informações suficientes para apresentar o documento e assegurar que as anotações correctas são apresentadas na régua vertical à esquerda.  O modelo é associado à régua quando o documento for definido.  A porção de código seguinte mostra o que acontece quando um documento é definido no visualizador de fonte.  O código true do SourceViewer foi simplificado para mais clareza:

public void setDocument(IDocument document, IAnnotationModel annotationModel) {
	...
	// create visual annotation model from the supplied model and store 
	// in fVisualAnnotationModel
	...
	if (fVerticalRuler != null)
		fVerticalRuler.setModel(fVisualAnnotationModel);

Desta forma, a régua fica associada ao modelo de anotações apropriado.   

Vamos abordar agora a régua propriamente dita.  É criada pelo editoe de texto e depois ligada ao visualizador do editor.  Dado que o exemplo de editor Java não define nenhum comportamento especial para réguas, herdará a régua conforme o definido no TextEditor.

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

O editor de texto utiliza uma CompositeRuler. Esta régua não tem apresentação visual própria.  A apresentação é facultada por uma lista de decoradores que mostram colunas (IVerticalRulerColumn) na régua.  Neste exemplo, é sempre adicionada uma coluna de régua que mostra anotações (AnnotationRulerColumn) e é adicionada uma coluna de régua de números de linha com base nas preferências do utilizador. A coluna da régua de anotações trata das especificidades da apresentação das imagens da anotação nas localizações devidas.

Apesar de todas as classes envolvidas na apresentação de uma regra, repare que o editor exemplo só precisava de constituir subclasses de classes do quadro para obter comportamento de régua.   O JavaDocumentProvider  herda um modelo de anotações de marcadores apropriado do FileDocumentProvider.  O JavaTextEditor herda a apresentação da régua do TextEditor.

Régua de descrição geral

Utiliza-se uma régua de descrição geral à direita da área de edição para mostrar anotações relativas a todo o documento.  Estas anotações são mostradas relativamente à sua posição no documento e não mudam de sítio quando o utilizador desloca o documento.   Existe geralmente uma anotação correspondente na régua vertical quando essa parte do documento fica visível.   

A régua vertical a seguir mostra que existem duas tarefas no documento e um marcador de texto.  Como o texto marcado está visível, a sua anotação também é apresentada à esquerda.

Régua vertical de descrição geral no editor Java

O utilizador pode navegar até à localização da anotação no código fazendo clique na própria anotação.

Os tipos de anotações apresentados na régua de descrição geral são determinados pela adição de tipos de anotações à régua.  Na porção de código seguinte do SourceViewerDecorationSupport, os tipos de anotações são dinamicamente adicionados à régua. (Consulte a secção seguinte para mais informações sobre 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();
} }

A régua de descrição geral também tem um IAnnotationAccess que é utilizado para prestar informações sobre determinada anotação como, por exemplo, o seu tipo e como deve ser apresentada.   O TextEditor utiliza um DefaultMarkerAnnotationAccess que interpreta anotações segundo os respectivos tipos de marcador e consulta as preferências do utilizador para ver quais os tipos de marcador que devem ser mostrados na régua de descrição geral.

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

Consulte a implementação do DefaultMarkerAnnotationAccess e MarkerAnnotation para mais detalhes sobre a apresentação de marcadores na régua de descrição geral.

Anotações de texto

Além de mostrar anotações nas réguas, um visualizador de fonte pode mostrar anotações como marcas #squiggly coloridas no texto.   

Marca #squiggly no editor Java

Voltaremos à criação do visualizador de fonte no 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;
}

A classe SourceViewerDecorationSupport trata muitas das decorações mostradas num visualizador de fonte, incluindo anotações de texto, margens coloridas, linhas de cursor coloridas e afins.  É configurada com as preferências do utilizador para poder responder a actualizações dinâmicas das alterações às preferências do utilizador.  A maioria dos editores não tem de obviar aos detalhes de composição destas decorações.   (Consulte SourceViewerDecorationSupport e classes relacionadas como, por exemplo, AnnotationPainter se for necessário.). O importante é saber quais as decorações disponíveis para que o SourceViewer e o respectivo SourceViewerDecorationSupport de suporte sejam devidamente configurados.

Configurar um SourceViewerDecorationSupport

Vejamos a configuração utilizada pelo TextEditor para suporte de decoração.

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());
}

Repare que as preferências de anotação são utilizadas para definir tipos de anotações para todas as anotações mostradas nas preferências de utilizador.  Isto inclui anotações que sejam contributos de qualquer plug-in e não se limita às anotações fornecidas pela área de trabalho.  Se não quiser mostrar todas as anotações disponíveis no editor, deverá sobrepor este método e configurar o SourceViewerDecorationSupport somente com os tipos que pretende mostrar.