Tekstin ja viivaimen koho-ohje

Käyttöympäristön tekstikehyksen koho-ohjeen tuen avulla voi toteuttaa koho-ohjeen (tai pikaohjeen) muokkausohjelman näyttämien viivainten ja tekstin päällä.

Koho-ohjeen tuki on valinnainen. Oletusarvon mukaan SourceViewerConfiguration ei asenna koho-ohjetta, koska ohjeessa esitettävää hyödyllistä yleistä tietoa ei ole. Jotta muokkausohjelma voi ottaa käyttöön tekstin tai viivaimen koho-ohjeen, sen lähdekoodin katseluohjelman kokoonpanon pitää olla määritetty määrittämään lisättävissä olevan koho-ohjeobjektin.

JavaSourceViewerConfiguration näyttää, mitkä metodit määrittävät koho-ohjetta:

public ITextHover getTextHover(ISourceViewer sourceViewer, String contentType) {
	return new JavaTextHover();
}
public IAnnotationHover getAnnotationHover(ISourceViewer sourceViewer) {
	return new JavaAnnotationHover();
}

Koho-ohjeen tukiluokat voi myös asentaa dynaamisesti SourceViewer-luokan yhteyskäytännön avulla (setTextHover ja setAnnotationHover). Kummastakaan asennustavasta ei ole erityistä ajonaikaista hyötyä, mutta kaikkien lisättävissä olevien toimintojen ohitusten laittaminen SourceViewerConfiguration -luokan aliluokkaan mahdollistaa kaikkien toiminnan ohitusten sijoittamisen samaan paikkaan.

Seuraavassa perehdytään tarkemmin sekä tekstin että viivaimen koho-ohjeisiin.

Tekstin koho-ohje

Tekstin koho-ohjeen avulla voi muokkausohjelmassa näkyvästä tekstistä tuoda esiin tietoja tekstimuodossa. Tähän käytetään ITextHover-rajapintaa.  Tekstin koho-ohje laskee sen alueen, jota käytetään koho-ohjeen tiedon lähteenä, ja ottaa huomioon siirtymän. Ohje esittää myös kyseisestä alueesta lisätietoja tekstimuodossa.  JavaTextHover on melko yksinkertainen. Se tarkastaa, sisältääkö tekstivalinta koho-ohjeelle annetun siirtymän.   Jos se sisältää siirtymän, toiminto määrittää valinta-alueen koho-ohjeen alueeksi. 

public class JavaTextHover implements ITextHover {

	...
	
	public IRegion getHoverRegion(ITextViewer textViewer, int offset) {
		Point selection= textViewer.getSelectedRange();
		if (selection.x <= offset && offset < selection.x + selection.y)
			return new Region(selection.x, selection.y);
		return new Region(offset, 0);
	}
}

Koho-ohje ottaa huomioon laskemansa koho-ohjeen alueen, poimii asiakirjasta valitun tekstin ja palauttaa sen koho-ohjeen tietoina.

public class JavaTextHover implements ITextHover {

	public String getHoverInfo(ITextViewer textViewer, IRegion hoverRegion) {
		if (hoverRegion != null) {
			try {
				if (hoverRegion.getLength() > -1)
					return textViewer.getDocument().get(hoverRegion.getOffset(), hoverRegion.getLength());
			} catch (BadLocationException x) {
			}
		}
		return JavaEditorMessages.getString("JavaTextHover.emptySelection"); 
	}
	...
}

Jos muokkausohjelmassa osoittaa jotakin valintaa, kohoteksti näyttää valinnan.

Valittua aluetta koskeva koho-ohjeen tieto

Monimutkaisemman kontekstitiedon avulla voi laskea hyödyllistä koho-ohjeen tietoa. Esimerkkejä aiheesta onJavaTextHover-luokassa, joka on toteutettu Java-kehitystyökalujen muokkausohjelman avulla.

Viivaimen koho-ohje

Pystyviivaimen koho-ohje on hyödyllinen silloin, kun esitetään rivejä koskevaa tietoa.  Koho-ohjeen luokka määritetään kuten yllä.  IAnnotationHover on viivaimen koho-ohjeobjektien rajapinta. Vaikka nimen perusteella voisi päätellä, että koho-ohje on suunniteltu viivaimen huomautuksia varten, muokkausohjelma voi määrittää, mihin ohjetta käytetään. Viivaimen koho-ohje palauttaa tiettyyn rivinumeroon liittyvän tietoa sisältävän merkkijonon riippumatta siitä, onko rivillä merkintöjä.   

Java-esimerkkimuokkausohjelman JavaAnnotationHover toteuttaa koho-ohjeen kaikilla riveillä. Rivinumeron avulla se poimii kaiken koho-ohjeen rivillä olevan tekstin ja palauttaa sen tietoa sisältävänä merkkijonona.

public String getHoverInfo(ISourceViewer sourceViewer, int lineNumber) {
	IDocument document= sourceViewer.getDocument();

	try {
		IRegion info= document.getLineInformation(lineNumber);
		return document.get(info.getOffset(), info.getLength());
			} catch (BadLocationException x) {
	}
		return null;
}

Koho-ohjeen tietoa viivaimessa

Asiakirja ja lähdekoodin katseluohjelma ovat koho-ohjeen käytettävissä. Sillä on siis käytössään kaikki tarvittava konteksti, jotta se voi toimia esitettävän tiedon perusteella monimutkaisissakin tilanteissa. Esimerkiksi huomautusmalli voidaan noutaa lähdekoodin katseluohjelmasta, jotta se voi tarjota koho-ohjeen tietoa pystyviivaimessa esitetyistä huomautuksista. Java-kehitystyökalujen JavaAnnotationHover mahdollistaa tämän.