Lähteenkatseluohjelmat ja huomautukset

Muokkausohjelma ja vastaava tekstinkatseluohjelma vastaavat suurelta osin asiakirjan esittämisen ja tarvittavien apuluokkien kokoonpanon toteutuksesta. (Perehdy kohtaan Katseluohjelmat, jos katseluohjelman käsite ei ole vielä tuttu.)  

TextViewer käsittelee kaikki alemman tason tiedot, joita tarvitaan asiakirjamallin ja sen osioiden määrittämiseksi värilliseksi ja muotoilluksi tekstiksi, jonka käyttäjä näkee. Lähdekoodin tyylin muokkausohjelmia varten on SourceViewer.  Lähdekoodin katseluohjelmiin kuuluu lähdekoodin huomautuksen käsite. Huomautukset voivat näkyä tekstin vasemmalla puolella pystyviivaimessa, oikealla puolella yleisviivaimessa tai  värillisenä aaltoviivana tekstirivin alapuolella.

SourceViewer-luokkaa ja sen apuluokkia käytetään koko AbstractTextEditor-luokan hierarkiassa.  org.eclipse.jface.text.source-paketti määrittää tämän katseluohjelman ja muut luokat, jotka tukevat huomautusten esittämistä.

Huomautukset ja viivaimet

Kuten osiotkin, huomautukset ovat kovin riippuvaisia muokattavan asiakirjan laadusta. Asiakirjan IAnnotationModel-rajapinta pidättää huomautuksia, luetteloi ne pyydettäessä, kuuntelee tekstinmuutoksia ja pitää huomautukset siten tekstin mukaisina. Huomautusmallit rekisteröidään laajennukseen org.eclipse.core.filebuffers.annotationModelCreation. Tämän laajennuspisteen avulla lisäosat voivat rekisteröidä luokan, joka luo kyseiselle tiedoston tunnisteelle sopivan huomautusmallin. Java-esimerkkimuokkausohjelma ei käytä tätä laajennuspistettä, joten se perii ympäristön määrittämän huomautusmallin.

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

Factory-luokka luo ResourceMarkerAnnotationModel-luokan niitä tiedostoja varten, joilla on jokin laajennus. Tämä luokka näyttää huomautukset, jotka edustavat työtilassa resurssien merkintää. (Lisätietoja merkinnöistä on kohdassa Resurssien merkinnät.) Se myös määrittää jokaiselle merkinnälle kuvan ja kuvauksen sekä tarkkailee resurssejaan merkintöjen muutosten varalta.

Jotta voidaan tutustua siihen, kuinka huomautusmalli näkyy tekstinmuokkausohjelmassa, perehdytään ensin ympäristön tekstinmuokkausohjelmaan ja sen viivaimiin ja huomautuksiin. Käyttäjä voi ohjata eri huomautusten näkymistä viivaimissa ja tekstissä Yleiset > Muokkausohjelmat > Tekstinmuokkausohjelmat > Huomautukset -oletusasetuksista.

Pystyviivain

Käyttöympäristön tekstinmuokkausohjelmat käyttävät muokkausalueen vasemmalla puolella sijaitsevaa pystyviivainta esittämään tekstirivin vieressä tekstialueita ja rivihuomautuksia.

Pystyviivain

Nämä huomautukset on kuvattu ResourceMarkerAnnotationModel-luokassa.  Tämä malli sijoitetaan SourceViewer-luokkaan, jossa muokkausohjelma alustaa lähdekoodin katseluohjelman. Seuraava koodikatkelma AbstractTextEditor-luokasta kuvaa, kuinka asiakirja ja huomautusmalli liitetään katseluohjelmaan.

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

Kun lähdekoodin katseluohjelmalle on määritetty sopiva asiakirja ja huomautusmalli, ohjelmalla on tarpeeksi tietoa asiakirjan esittämiseen ja sen varmistamiseen, että pystyviivaimessa esitetään oikeat huomautukset. Malli liitetään viivaimeen, kun asiakirja on määritetty. Seuraava koodikatkelma kuvaa, mitä asiakirjalle tapahtuu, kun se sijoitetaan lähdekoodin katseluohjelmaan. Alkuperäistä, kohdassa SourceViewer esiintyvää koodia on pelkistetty selvyyden vuoksi:

public void setDocument(IDocument document, IAnnotationModel annotationModel) {
	...
	// luo annetusta mallista visuaalinen huomautusmalli ja tallenna se 
	// kohtaan fVisualAnnotationModel
	...
	if (fVerticalRuler != null)
		fVerticalRuler.setModel(fVisualAnnotationModel);

Tällä tavalla viivain voidaan siis liittää sopivaan huomautusmalliin.  

Seuraavaksi perehdytään viivaimeen. Viivaimen luo tekstinmuokkausohjelma, minkä jälkeen viivain liitetään muokkausohjelman katseluohjelmaan. Koska Java-esimerkkimuokkausohjelma ei määritä viivaimille mitään erityistoimintoja, se perii viivaimen sellaisena kuin se on määritetty luokassa TextEditor.

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

Tekstinmuokkausohjelma käyttää CompositeRuler-luokkaa. Tällä viivaimella ei ole omaa ulkoasua.  Viivaimen esityksen luovat koristelutoiminnot, jotka näyttävät viivaimessa sarakkeet (IVerticalRulerColumn). Tässä esimerkissä lisätään aina sellainen viivaimen sarake, joka näyttää huomautuksia (AnnotationRulerColumn), ja rivinumeroa ilmaiseva viivaimen sarake lisätään käyttäjän oletusasetusten perusteella. Huomautuksia sisältävän viivaimen sarake ohjaa huomautusten kuvien esittämistä sopivassa sijainnissa.

Huomaa, että vaikka viivaimen esittämiseen tarvitaan lukuisia luokkia, esimerkkimuokkausohjelman tarvitsi viivaimen toimintojen toteuttamiseksi ainoastaan tehdä kehyksen luokista aliluokkia.   JavaDocumentProvider  perii sopivan merkintöjen huomautusmallin FileDocumentProvider-luokalta.  JavaTextEditor perii viivaimen esitysmuodon TextEditor-luokalta.

Yleisviivain

Muokkausalueen oikealla puolella sijaitseva yleisviivain näyttää koko asiakirjaa koskevat huomautukset. Huomautukset esitetään niihin liittyvän asiakirjan kohdan yhteydessä eivätkä ne liiku, kun käyttäjä selaa asiakirjaa.  Pystyviivaimessa näkyy yleensä yleisviivaimen huomautusta vastaava huomautus, kun kyseinen asiakirjan osa on näkyvissä.  

Alla olevasta pystysuuntaisesta viivaimesta näkyy, että asiakirjassa suoritetaan kahta tehtävää ja että asiakirjaan on lisätty yksi kirjanmerkki. Koska kirjanmerkillä merkitty teksti on näkyvissä, sitä koskeva huomautus näkyy vasemmalla.

Pystysuuntainen yleisviivain Java Editor-muokkausohjelmassa

Käyttäjä voi siirtyä koodissa huomautuksen kohtaan napsauttamalla huomautusta.

Yleisviivaimessa näkyvien huomautusten lajeja voi lisätä. Seuraavassa kohdasta SourceViewerDecorationSupport peräisin olevassa koodikatkelmassa huomautuslajeja lisätään viivaimeen dynaamisesti.(Seuraavassa osiossa on lisätietoja aiheesta 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();
} }

Yleisviivaimessa on myös IAnnotationAccess-rajapinta, jonka avulla saa lisätietoja huomautuksista, kuten siitä, mikä huomautuksen laji on kyseessä ja miten huomautus esitetään. TextEditor-luokka käyttää DefaultMarkerAnnotationAccess-luokkaa, joka tulkitsee huomautukset niiden merkintöjen lajien perusteella ja tarkistaa käyttäjän oletusasetuksista, mitä merkinnän lajeja yleisviivaimessa tulee näyttää.

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

DefaultMarkerAnnotationAccess- ja MarkerAnnotation-luokkien toteutuksesta käy ilmi lisää yksityiskohtia merkintöjen esittämisestä yleisviivaimessa.

Tekstihuomautukset

Lähdekoodin katseluohjelma voi näyttää huomautuksia viivainten lisäksi huomautuksia. Tekstissä ne näkyvät värillisenä aaltoviivana.  

Java Editor -muokkausohjelman aaltoviivaa

Lähdekoodin katseluohjelman luontia tarkastellaan kohdassa 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;
}

SourceViewerDecorationSupport-luokka käsittelee monia lähdekoodin katseluohjelmassa näkyviä koristeluita, esimerkiksi tekstihuomautuksia ja värillisiä kohdistimen viivoja.  Siihen on määritetty käyttäjän oletusasetukset, jotta se voi reagoida oletusasetusten muutoksiin dynaamisesti. Useimpien muokkausohjelmien ei tarvitse puuttua siihen, miten nämä koristelut maalataan. (Katso lisätietoja kohdasta SourceViewerDecorationSupport ja siihen liittyvistä luokista kohdasta AnnotationPainter).  Tärkeintä on tietää, mitkä koristelut ovat käytettävissä, jotta SourceViewer ja sitä tukeva SourceViewerDecorationSupport voidaan määrittää oikein.

SourceViewerDecorationSupport-luokan määrittäminen

Seuraavaksi perehdytään kokoonpanoon, jota TextEditor-luokka käyttää koristelujen tukemiseen.

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

Huomaa, että huomautusten oletusasetukset määrittävät kaikkien käyttäjän oletusasetuksissa näkyvien huomautusten lajeja. Niihin kuuluvat kaikkien lisäosien lisäämät huomautukset, eivät pelkästään työympäristön huomautukset. Jos et halua näyttää muokkausohjelmassa kaikkia käytettävissä olevia huomautuksia, ohita tämä metodi ja määritä SourceViewerDecorationSupport vain niille huomautusten lajeille, jotka haluat näkyviin.