Usein käyttäjän edellytetään antavan tekstitietoja yksinkertaiseen kenttään, kuten tekstikenttään tai yhdistelmäruutuun. Vaikka nämä kentät täyttävä sovelluskoodi on yleensä huomattavasti yksinkertaisempaa kuin monimutkaisen widget-objektin, esimerkiksi taulukon tai rakenteen, täyttävä koodi, nämä "yksinkertaiset" kentät yleensä kuormittavat käyttäjää paljon enemmän. Käyttäjän on selvitettävä, mitkä kentät edellyttävät sisältöä, onko kentän sisältö kelvollinen ja mitä valintoja odotetaan. Kenttien aputoiminnon JFace-tuki sisältää luokkia, jotka ohjaavat käyttäjää syötetehtävissä.
Paketti org.eclipse.jface.fieldassist auttaa kahdella tavalla. Koristeltujen kenttien tuen avulla voit sisällyttää kuvakoristeluja, jotka antavat käyttäjälle tietoa kentän tilasta. Sisältöehdotuksen tuen avulla voit toteuttaa sisältötuen ponnahdusikkunan, joka antaa käyttäjälle sisältövaihtoehtoja.
Koristeltujen kenttien avulla voit sijoittaa kuvakoristeluja ikkunaan tai valintaikkunaan määritettyjen kenttien viereen. Koristelut voi sijoittaa yhden kentän neljästä kulmasta viereen. Kuten katseluohjelmat, koristellut kentät lisäävät SWT-ohjausobjektin toiminnallisuutta, mutta perustana olevaa ohjausobjektia voi yhä käyttää. DecoratedField-kohteen ohjelmointirajapinnan avulla voit lisätä, piilottaa ja näyttää koristeluja kentän vieressä. Perustana olevaa ohjausobjektia voi käyttää, joten aiemman SWT-ohjelmointirajapinnan avulla voi vaikuttaa ohjausobjektiin, esimerkiksi määrittää sen sisällön, värin ja fontin.
Ulkopuolelta katsottuna koristeltu kenttä toimii kuten yksittäinen ohjausobjekti. Sisäisesti sen sijaan koristeltu kenttä on koostettu ohjausobjekti, jonka avulla hallitaan kentän ja sen koristelujen asettelua. Useimmiten tällä ei ole merkitystä työasemasovelluksen kannalta. Se tarkoittaa kuitenkin, että koristellun kentän on luotava ohjausobjekti. Katso esimerkiksi seuraavaa katkelmaa, jossa sovellus luo tekstiohjausobjektin yhteen valintaikkunoistaan:
... // Luo tekstikenttä Text text = new Text(parent, SWT.BORDER); text.setText("jotain tekstiä"); ...
Kentän koristelu edellyttää, että kenttä luodaan seuraavasti:
... // Luo koristeltu tekstinhallinnan kenttä DecoratedField field = new DecoratedField(parent, SWT.BORDER, new TextControlCreator()); Text text = (Text)field.getControl(); text.setText("jotain tekstiä"); ...
Kentän luomisessa käytetään samoja pää- ja tyyliosia, joiden avulla myös perusohjausobjekti luodaan ja sitä käytetään. Pääasiallinen ero koodissa on se, että käytettävissä onIControlCreator-ilmentymä, joka luo kentän tarvitseman tietyn ohjausobjektin. Tekstikenttien ohjausobjektien luontiin voit käyttää luokkaa TextControlCreator. Toisaalta voit myös luoda minkä tahansa muun ohjausobjektin, kuten yhdistelmäruudun tai numerotoiminnon, toteuttamalla IControlCreator-rajapintaa.
Kun koristeltu kenttä on luotu, siihen voi lisätä koristeluja yhteen neljästä sijainnista. Koristelun sijaintipaikka määritetään SWT-sijaintivakioiden avulla. Voit lisätä koristelun määrittämälläFieldDecoration-kohteen, joka määrittää koristelun kuvan ja valinnaisen kuvaustekstin, joka voidaan näyttää käyttäjän siirtäessä osoittimen koristelun kohdalle.
... // Luo kentän koristelu ja lisää se kenttään Image image = JFaceResources.getImage("myplugin.specialimage"); FieldDecoration mySpecialDecoration = new FieldDecoration(image, "Tämä on erityinen kenttä"); field.addFieldDecoration(mySpecialDecoration, SWT.TOP | SWT.LEFT, false); ...
Totuusarvoparametrin avulla määritetään, näytetäänkö koristelu vain, kun kohdistus on ohjausobjektissa, vai koko ajan. Tässä tapauksessa koristelu on näkyvissä koko ajan. Voi kuitenkin olla muita tilanteita, joissa koristelu on piilotettava tai näytettävä. Seuraavan katkelman avulla voit piilottaa koristelun, joka on jo luotu.
... // On ilmennyt jotain, minkä takia haluan piilottaa koristelun field.hideDecoration(mySpecialDecoration); ...
Jos koristelun kuvaus tai kuva päivitetään, kentälle on ilmoitettava, jotta koristelu voidaan piirtää uudestaan.
... // Kenttä on jostain syystä erityisen tärkeä mySpecialDecoration.setDescription("Tämä on erityisen tärkeä kenttä"); field.updateDecoration(mySpecialDecoration); ...
Kun asettelet koristeltua kenttää valintaikkunaan tai ikkunaan, asettele kentän asettelun ohjausobjekti, älä perustana olevaa yksinkertaista ohjausobjektia. Tarkastele tekstiohjausobjektin luontikoodia. Kun asettelet tekstiohjausobjektia, sovellus määrittää asettelutiedot ohjausobjektiin.
... // Luo tekstikenttä Text text = new Text(parent, SWT.BORDER); text.setText("jotain tekstiä"); // Määritä asettelutiedot GridData data = new GridData(IDialogConstants.ENTRY_FIELD_WIDTH, SWT.DEFAULT); text.setLayoutData(data); ...
Kun asettelet koristeltua kenttää, sovelluksen tulee määrittää asettelutiedot kentän asettelun ohjausobjektiin. Halutun asettelun mukaan määräytyen kentän kokoa voi olla tarpeen muuttaa koristelun kokoa vastaavaksi.
... // Luo koristeltu tekstinhallinnan kenttä DecoratedField field = new DecoratedField(main, SWT.BORDER, new TextControlCreator()); Text text = (Text)field.getControl(); text.setText("jotain tekstiä"); // Määritä asettelutiedot GridData data = new GridData(IDialogConstants.ENTRY_FIELD_WIDTH + FieldDecorationRegistry.getDefault().getMaximumDecorationWidth(), SWT.DEFAULT); field.getLayoutControl().setLayoutData(data); ...
Kenttien aputoiminnon tuki ei edellytä tai oleta, että käytät vain koristeltuja kenttiä tietyssä valintaikkunassa tai ikkunassa. Ikkunan asettelu voi kuitenkin käydä monimutkaiseksi, kun koristeltuja kenttiä käytetään yhdessä yksinkertaisten ohjausobjektien kanssa. Koristeltujen ja koristelemattomien kenttien tasauksessa on huomioitava koristelun leveyden aiheuttama sisennys. Koristelun leveys on yksinkertaisesti sen kuvan leveys. Asiat käyvät kuitenkin mutkikkaammiksi, jos koristeluissa on eri leveydet. Tässä tapauksessa voit yksinkertaistaa asioita rekisteröimällä kaikki koristelut FieldDecorationRegistry-kohteeseen.
Kenttäkoristelurekisterin avulla voit rekisteröidä ja käyttää kenttäkoristeluja merkkijonotunnuksen avulla. Tämä on kätevä tapa viitata koristeluihin sovelluksessa. Voit määrittää ohjelmointirajapinnan, joka näyttää koristelujen tunnukset, jos haluat saattaa ne muiden lisäosien käyttöön. Huomaa, että koristelun rekisteröinti ei hallitse koristelujen sisältämien kuvien elinkaarta. Sovellus voi ratkaista, kuinka kuvia hallitaan. Esimerkiksi JFace-kuvarekisterin avulla voidaan rekisteröidä ja hallita kuvan elinkaarta. Vaihtoehtoisesti sovellus voi luoda kuvan tarpeen mukaan ja poistaa sen, kun sitä ei enää tarvita. Rekisteröintimetodien javadocissa kohteessa FieldDecorationRegistry selitetään eri tavat, joiden avulla kuvat voi määrittää koristelun rekisteröinnin yhteydessä.
Koristelujen rekisteröinti kenttäkoristelurekisteriin yksinkertaistaa myös asetteluprosessia, kun käytössä on erilaisia koristeltuja (ja koristelemattomia) kenttiä. Oletusarvon mukaan koristeltu kenttä kysyy kenttäkoristelurekisteristä koristelun enimmäisleveyttä ja varmistaa, että kaikki koristelut käyttävät kyseistä leveyttä. Tästä seuraa, että kaikki koristellut kentät asettuvat tasaisesti huolimatta yksittäisten kenttien koristeluista. Voit tasata koristelemattomat kentät FieldDecorationRegistry-yhteyskäytännön avulla käyttämällä suurimman koristelun leveyttä ja luomalla tarvittavan sisennyksen.
... // Luo tekstikenttä Text text = new Text(parent, SWT.BORDER); text.setText("jotain tekstiä"); // Määritä asettelutiedot GridData data = new GridData(); data.horizontalAlignment = SWT.FILL; data.horizontalIndent = FieldDecorationRegistry.getDefault().getMaximumDecorationWidth(); text.setLayoutData(data); ...
Vaikka kenttien aputoiminnon tuki ei määrää, kuinka koristeluja käytetään, rekisteri määrittää myös vakiokoristelut, joiden avulla sovellukset voivat näyttää tietyt kentän tilat. Esimerkiksi seuraavassa katkelmassa käytetään pakollisten kenttien vakiokoristelua:
... // Luo koristeltu kenttä, jolla on pakollisen kentän koristelu. DecoratedField field = new DecoratedField(main, SWT.BORDER, new TextControlCreator()); FieldDecoration requiredFieldIndicator = FieldDecorationRegistry.getDefault(). getFieldDecoration(FieldDecorationRegistry.DEC_REQUIRED); field.addDecoratedField(requiredFieldIndicator, SWT.BOTTOM | SWT.LEFT, false); ...
Kenttien koristelun lisäksi sovellukset voivat antaa sisältöehdotuksia, jotka aktivoivat kentän sisältöponnahdusikkunan. Voit asentaa ContentProposalAdapter-kohteen haluamaasi ohjausobjektiin, jos haluat tarjota tämän toiminnon. Seuraavan katkelman avulla voit asentaa sisältöehdotuksen sovittimen tekstiohjausobjektiin. Huomaa, että tämä tekstin ohjausobjekti voi olla ohjausobjekti, jonka sovellus on luonut suoraan tai joka on noudettu koristellusta kentästä.
... autoActivationCharacters = new char[] { '#', '(' }; keyStroke = KeyStroke.getInstance("Ctrl+Space"); // oleta, että myTextControl on jo luotu jollakin tapaa ContentProposalAdapter adapter = new ContentProposalAdapter( myTextControl, new TextContentAdapter(), new SimpleContentProposalProvider(new String [] {"ProposalOne", "ProposalTwo", "ProposalThree"}), keyStroke, autoActivationCharacters);
Jotta ohjausobjektin sisältö voidaan noutaa ja asettaa, kun käyttäjä valitsee ehdotuksen ponnahdusikkunassa, sovittimelle on toimitettava IControlContentAdapter-ilmentymä, joka voi noutaa ja asettaa tietynlaisen ohjausobjektin sisällön. Tekstikentissä voit käyttää luokkaa TextContentAdapter. Voit kuitenkin halutessasi toteuttaa IControlContentAdapter-kohteen ja käyttää sisältöehdotuksen sovitinta minkä tahansa muun ohjausobjektin kanssa.
Kun luot sisältöehdotuksen sovittimen, määritä myös IContentProposalProvider-ilmentymä, josta ehdotukset noudetaan. Tämä toimittaja palauttaa sisältöehdotustaulukon. Ehdotukset määritetään IContentProposal-kohteen ilmentyminä, joista ehdotuksen nimiön ja sisällön lisäksi voi noutaa muuta tietoa, kuten ehdotuksen tarkan kuvauksen.
Edellisessä esimerkissä käytetään SimpleContentProposalProvider-kohdetta. Tämä toimittaja määritetään määrittämällä yksinkertainen String-taulukko sisältöehdotuksiksi. Yksinkertainen toimittaja toteuttaa tarvittavan yhteyskäytännön, jonka avulla määritetään kullekin merkkijonolle vastaavuus odotettuun IContentProposal-kohteeseen. IContentProposalProvider-kohteen joustavuuden ansiosta voit toteuttaa ehdotuksen toimittajan, jossa on lisäominaisuuksia, esimerkiksi suodattaa ehdotukset ohjausobjektin sisällön perusteella, lisätä selittäviä nimiöitä ponnahdusikkunaan varsinaisen lisättävän sisällön sijasta ja määrittää kohdistimen odotetun sijainnin, kun ehdotus on lisätty. Jos haluat tietoja lisäominaisuuksista, katso Kenttien aputoiminnon esimerkki ja hae IContentProposalProvider-kohteen toteuttajia.
Sisältöehdotuksen sovittimen perusmääritys sisältää ohjausobjektin, jota ehdotukset koskevat, ohjausobjektin sisällön muuttamiseen käytetyn sisällön sovittimen ja ehdotuksen toimittajan, joka määrittää ponnahdusikkunan ehdotusluettelon. Näiden perusseikkojen lisäksi on useita muita tapoja, joiden avulla sisältöehdotuksen sovittimen voi määrittää:
Kenttien aputoiminnon tuki JFace-tasolla tekee sovelluksesta hyvin joustavan sen suhteen, kuinka haluat koristella kentät ja näyttää ehdotuksia kentän sisällöksi. Tämä on toivottavaa erillisissä JFace-sovelluksissa ja erillisissä laajennetun työasemaohjelmiston sovelluksissa. Jos sovelluksen on tarkoitus integroida muiden lisäosien kanssa, esimerkiksi Eclipse SDK:n tai muiden toimittajien lisäosien kanssa, kenttien aputoiminnon tukea kannattaa käyttää johdonmukaisesti muiden lisäosien kanssa. Työympäristö määrittää apuohjelmaluokat, jotka käyttävät kenttien aputoimintoa tietyissä vuorovaikutuksissa.
Esimerkiksi luokka ContentAssistField luo kentän, johon kuuluu hehkulamppukoriste. Se osoittaa käyttäjälle, että sisällön aputoiminto on käytettävissä. Se määrittää myös sisältöehdotuksen sovittimen sisällön aputoiminnon tyylin lisäykselle. Lopuksi se toimittaa käsittelytoiminnon työympäristötason sisällön aputoimintokomennolle, jotta sisältöehdotuksen ponnahdusikkuna avataan, kun käyttäjä painaa näppäintä tai liipaisusarjaa, joka on määritetty työympäristön näppäinsidonnoissa. Lisätietoja näistä apuohjelmaluokista on paketissa org.eclipse.ui.fieldassist.
Tämä paketti kehittyy työympäristön alkaessa käyttää kenttien aputoimintoa laajemmin ja standardoidessa koristelujen käytön tietyissä kenttätiloissa.