Visualizzatori di origine e annotazioni

La struttura del testo della piattaforma fornisce classi di interfaccia utente che implementano una presentazione ricca di un documento di un editor.   

L'editor e il visualizzatore testo corrispondente sono i principali responsabili dell'implementazione della presentazione del documento e della configurazione delle classi helper necessarie.  (Se non si ha familiarità con il concetto di visualizzatore, fare riferimento alla sezione Visualizzatori).  

Un TextViewer gestisce tutti i dettagli di livello inferiore di associazione del modello di documento e delle relative suddivisioni nel testo colorato e formattato visualizzato dall'utente.  Per gli editor dello stile del codice di origine viene fornito un SourceViewer.  Un visualizzatore di origine introduce la nozione di annotazioni del codice di origine.  Tali annotazioni possono essere visualizzate in un righello verticale a sinistra del testo, in un righello della panoramica a destra del testo  oppure come linee irregolari colorate che sottolineano il testo.

SourceViewer e le relative classi helper vengono utilizzati in tutta la gerarchia AbstractTextEditor.  Il pacchetto org.eclipse.jface.text.source definisce questo visualizzatore e le altre classi che supportano la presentazione delle annotazioni.

Annotazioni e righelli

Come si è già visto, un fornitore di documenti fornisce, oltre al documento, un modello per le relative annotazioni, IAnnotationModel.  Tale modello contiene le annotazioni, le conta su richiesta e attende le modifiche del testo per aggiornare le annotazioni in base al testo.   JavaDocumentProvider eredita il comportamento definito in FileDocumentProvider e quindi anche il relativo modello di annotazioni.

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 definisce un modello per le annotazioni che rappresentano un indicatore su una risorsa nello spazio di lavoro.  (Per ulteriori informazioni sugli indicatori, vedere Indicatori delle risorse).  Esso assegna un'immagine e una descrizione a ciascun indicatore e ne controlla le risorse per eventuali modifiche.

Per vedere come un modello di annotazioni viene visualizzato in un editor di testo, verrà esaminato l'editor di testo della piattaforma e l'uso che ne viene fatto di righelli e annotazioni.  L'utente può controllare le specifiche modalità di visualizzazione nei righelli e nel testo delle diverse annotazioni nelle preferenze Workbench > Editor > Editor di testo della scheda Annotazioni.

Righello verticale

Negli editor di testo della piattaforma viene utilizzato un righello verticale a sinistra dell'area di modifica per visualizzare intervalli di testo e annotazioni basate sulle righe adiacenti alla relativa riga di testo.

Tali annotazioni sono descritte nel ResourceMarkerAnnotationModel fornito.  Questo modello viene impostato nel SourceViewer quando il visualizzatore di origine viene inizializzato dall'editor.  Il frammento di AbstractTextEditor che segue mostra come il documento e il modello di annotazioni sono associati al visualizzatore.

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

Una volta configurato con il modello di documento e di annotazioni appropriato, il visualizzatore di origine è dotato di un numero di informazioni sufficiente per presentare il documento e per garantire che nel righello verticale a sinistra vengano visualizzate le annotazioni corrette.  Il modello viene associato al righello quando viene impostato il documento.  Il frammento di codice che segue mostra cosa accade quando un documento viene impostato nel visualizzatore di origine.  Per renderlo più chiaro, è stato semplificato rispetto al codice effettivo in SourceViewer:

public void setDocument(IDocument document, IAnnotationModel annotationModel) {
	...
	// creare un modello di annotazione visivo dal modello fornito e memorizzarlo
	// in fVisualAnnotationModel
	...
	if (fVerticalRuler != null)
		fVerticalRuler.setModel(fVisualAnnotationModel);

In questo modo, il righello viene associato al modello annotazioni appropriato.  

Verrà illustrato il righello.  Il righello viene creato dall'editor di testo, quindi connesso con il visualizzatore dell'editor.  L'esempio di editor Java non definisce alcun comportamento particolare per i righelli, pertanto eredita il righello come definito in TextEditor.

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

L'editor di testo utilizza un CompositeRuler. Questo righello non è dotato di una propria presentazione visiva.  La presentazione viene fornita da un elenco di decoratori che mostrano colonne (IVerticalRulerColumn) nel righello.  In questo esempio viene sempre aggiunta una colonna del righello che mostra annotazioni (AnnotationRulerColumn) e viene aggiunta una colonna del righello del numero di riga in base alle preferenze dell'utente. La colonna delle annotazioni gestisce i particolari della visualizzazione delle immagini delle annotazioni nelle posizioni appropriate.

Nonostante tutte le classi coinvolte nella visualizzazione di un righello, si osservi che, per ottenere il comportamento del righello, l'editor di esempio ha semplicemente creato sottoclassi delle classi delle strutture.   JavaDocumentProvider eredita un modello di annotazioni di indicatore appropriato da FileDocumentProvider.  JavaTextEditor eredita la presentazione del righello da TextEditor.

Righello della panoramica

Un righello della panoramica posto sul lato destro dell'area di modifica viene utilizzato per mostrare annotazioni che riguardano tutto il documento.  Tali annotazioni vengono visualizzate relativamente alla posizione che hanno nel documento e non cambiano posizione quando l'utente scorre il documento.  Generalmente è presente un'annotazione corrispondente sul righello verticale quando la porzione di documento interessata è visibile.  

Il righello verticale indica che nel documento sono presenti due attività e un solo segnalibro.   Dal momento che è visibile il testo con segnalibro, a sinistra è mostrata anche la relativa annotazione.

Righello verticale nell'Editor Java

L'utente può individuare la posizione dell'annotazione nel codice facendo clic sull'annotazione.

I tipi di annotazioni visualizzati nel righello della panoramica vengono stabiliti aggiungendo tipi di annotazioni al righello.  Nel frammento di codice da SourceViewerDecorationSupport, i tipi di annotazioni vengono aggiunti dinamicamente al righello. (Per ulteriori informazioni su SourceViewerDecorationSupport, fare riferimento alla sezione che segue).

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

Insieme al righello della panoramica viene inoltre fornito un IAnnotationAccess che viene utilizzato per ottenere informazioni su una particolare annotazione, ad esempio il tipo e le modalità di visualizzazione.  TextEditor utilizza un DefaultMarkerAnnotationAccess che interpreta le annotazioni in base ai tipo di indicatori e consulta le preferenze dell'utente per sapere quali tipi di indicatori devono essere visualizzati nel righello della panoramica.

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

Per ulteriori dettagli sulla presentazione degli indicatori nel righello della panoramica, consultare l'implementazione di DefaultMarkerAnnotationAccess e MarkerAnnotation .

Annotazioni del testo

Oltre alle annotazioni nei righelli, un visualizzatore di origine può visualizzare le annotazioni sotto forma di righe irregolari colorate nel testo.  

Righe irregolari nell'Editor Java

Verrà nuovamente illustrata la creazione del visualizzatore di origine in 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 classe SourceViewerDecorationSupport gestisce molte delle decorazioni mostrate in un visualizzatore di origine, tra cui annotazioni di testo, margini colorati, linee del cursore colorate e altro ancora.  Viene configurata con le preferenze dell'utente in modo che possa rispondere agli aggiornamenti dinamici delle modifiche di tali preferenze.s  Per la maggior parte degli editor non è necessario specificare i dettagli relativi alle modalità di disegno di queste decorazioni.   (Se questa operazione è necessaria, fare riferimento a SourceViewerDecorationSupport e alle classi correlate, ad esempio AnnotationPainter).  È importante sapere quali sono le decorazioni disponibili al fine di configurare correttamente SourceViewer e la relativa classe di supporto SourceViewerDecorationSupport.

Configurazione di una classe SourceViewerDecorationSupport

Verrà illustrata la configurazione utilizzata da TextEditor per il supporto di decorazione.

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

Si tenga presente che le preferenze di annotazione vengono utilizzate per definire i tipi per tutte le annotazioni visualizzate nelle preferenze dell'utente.  Sono comprese le annotazioni aggiunte dai plug-in e non si limitano a quelle fornite dal workbench.  Se non si desidera visualizzare tutte le annotazioni disponibili nell'editor, è necessario sostituire questo metodo e configurare SourceViewerDecorationSupport solo con i tipi che si desidera visualizzare.

Copyright IBM Corporation e altri 2000, 2003.