Felthjelp

Ofte forventes det at en bruker oppgir tekstopplysninger i et enkelt felt f.eks. et tekstfelt eller en kombinasjonsboks. Selv om applikasjonskoden som fyller ut disse feltene, generelt er mye enklere enn koden som fyller ut en kompleks widget som f.eks. en tabell eller en treoversikt, betyr disse "enkle" feltene vanligvis mer arbeid for brukeren. Brukeren må identifisere hvilke felt som krever innhold, hvorvidt et felt inneholder gyldig innhold, og hvilke valg som forventes. JFaces felthjelp har klasser som hjelper brukeren med utfyllingsoppgavene.

Pakken org.eclipse.jface.fieldassist gir hjelp på to måter: Støtte for dekorerte felt gjør det mulig å inkludere bildedekorasjoner som opplyser brukeren om status for et bestemt felt. Innholdsforslag gjør det mulig for deg å gi innholdshjelp som gir brukeren innholdsvalg.

Dekorerte felt

Ved hjelp av dekorerte felt kan du plassere bildedekorasjoner ved siden av felt som er definert i et vindu eller en dialogboks. Dekorasjoner kan plasseres ved siden av et av de fire hjørnene i et felt. I likhet med visningsprogrammer er dekorerte felt ment å bidra med funksjonalitet til en SWT-kontroll, samtidig som de gir tilgang til den underliggende kontrollen. APIet for DecoratedField gjør det mulig for deg å legge til, skjule og få frem dekorasjoner ved siden av et felt. Tilgang til den underloggende kontrollen gis for at du skal kunne bruke eksisterende SWT-API til å påvirke den underliggende kontrollen, for eksempel definere innhold, farge eller font.

Opprette et dekorert felt

Fra utsiden oppfører et dekorert felt seg som en enkeltkontroll. Internt bruker dekorerte felt en sammensatt kontroll til å styre layouten til feltet og dets dekorasjoner. For de meste skulle ikke dette spille noen rolle for klientapplikasjonen. Det betyr imidlertid at det dekorerte feltet må utføre den faktiske opprettelsen av kontrollen. Ta for eksempel følgende snutt, der en applikasjon oppretter en tekstkontroll i en av sine dialogbokser:

...
// Opprett et tekstfelt
Text text = new Text(parent, SWT.BORDER);
text.setText("litt tekst"); 
...

For at dette feltet skal kunne dekoreres, må feltet opprettes slik:

...
// Opprett et dekorert felt for en tekstkontroll
DecoratedField field = new DecoratedField(parent, SWT.BORDER, new TextControlCreator());
Text text = (Text)field.getControl();
text.setText("litt tekst");
...

Samme overordnet og stilbiter som ville bli brukt til å opprette den grunnleggende kontrollen, brukes også til å opprette et dekorert felt. Den viktigste forskjellen er i koden er at det besørges en forekomst av IControlCreator som oppretter den bestemte typen kontroll som er ønsket i feltet. For tekstfelt kan du bruke klassen TextControlCreator til å opprette kontrollen. Du har imidlertid også fleksibilitet til å implementere IControlCreator for å opprette en annen type kontroll i feltet, for eksempel en kombinasjonsboks eller en spinner.

Bruke dekorasjoner

Når et dekorert felt opprettes, kan dekorasjoner legges til, på ett av fire steder. SWT-plasseringskonstanter brukes til å oppgi hvor dekorasjonen skal plasseres. For å legge til en dekorasjon må du oppgi en FieldDecoration, som definerer bildet for dekorasjonen, og (valgfritt) beskrivende tekst som kan vises når brukeren beveger pekeren over dekorasjonen.

...
// Opprett en feltdekorasjon og legg den til feltet
Image image = JFaceResources.getImage("myplugin.specialimage");
FieldDecoration mySpecialDecoration = new FieldDecoration(image, "Dette feltet er spesielt");
field.addFieldDecoration(mySpecialDecoration, SWT.TOP | SWT.LEFT, false);
...

Denne boolske parameteren brukes til å oppgi hvorvidt dekorasjonen skal vises bare når kontrollen har fokus, eller hele tiden. I dette tilfellet skal dekorasjonen vises hele tiden. Det kan imidlertid være andre ganger da dekorasjonen bør skjules eller vises. Følgende snutt skjuler en dekorasjon som allerede er opprettet:

...
// Det har skjedd noe som gjør at jeg vil skjule dekorasjonen
field.hideDecoration(mySpecialDecoration);
...

Hvis bildet eller beskrivelsen for en dekorasjon oppdateres, bør dette feltet varsles, slik at dekorasjonen kan tegnes på nytt.

...
// Noe har gjort dette feltet helt spesielt
mySpecialDecoration.setDescription("Dette feltet er helt spesielt");
field.updateDecoration(mySpecialDecoration);
...

Utforme dekorerte og ikke-dekorerte felt

Når du utformer et dekorert felt i en dialogboks eller et vindu, bør du utforme feltets layoutkontroll snarere enn den underliggende enkle kontrollen. Ta en ny titt på koden for å opprette en tekstkontroll. Når du utformer en tekstkontroll, definerer applikasjonen layoutdata for kontrollen.

...
// Opprett et tekstfelt
Text text = new Text(parent, SWT.BORDER);
text.setText("litt tekst");
// Definer layoutdata
GridData data = new GridData(IDialogConstants.ENTRY_FIELD_WIDTH, SWT.DEFAULT);
text.setLayoutData(data); 
...

Når du utformer et dekorert felt, bør applikasjonen definere layoutdataene på feltets layoutkontroll. Avhengig av ønsket layout kan størrelsen på feltet justeres for størrelsen på dekorasjonen.

...
// Opprett et dekorert felt for en tekstkontroll
DecoratedField field = new DecoratedField(main, SWT.BORDER, new TextControlCreator());
Text text = (Text)field.getControl();
text.setText("litt tekst");
// Definer layoutdata
GridData data = new GridData(IDialogConstants.ENTRY_FIELD_WIDTH + 
   FieldDecorationRegistry.getDefault().getMaximumDecorationWidth(), SWT.DEFAULT);
field.getLayoutControl().setLayoutData(data); 
...

Felthjelpstøtten krever ikke eller antar ikke at du bruker bare dekorerte felt i en bestemt dialogboks eller vindu. Layouten til vinduet kan imidlertid bli litt mer komplisert når dekorerte felt blandes med enkle kontroller. For å justere dekorerte og ikke-dekorerte felt må du ta hensyn til innrykket du får pga. dekorasjonsbredden. Bredden på en dekorasjon er ganske enkelt bredden at bildet. Det kan imidlertid bli mer komplisert hvis du bruker dekorasjoner av forskjellig bredde. I så fall kan du forenkle ting ved å registrere alle dine dekorasjoner i FieldDecorationRegistry.

Feltdekorasjonsregister

Ved hjelp av feltdekorasjonsregisteret kan du registrere og få tilgang til feltdekorasjoner med en streng-ID. Dette innebærer en praktisk måte for deg å referere til dekorasjoner på i hele applikasjonen. Du kan velge å definere et API som eksponerer dekorasjons-IDene, hvis du vil gjøre dem tilgjengelige for andre plugin-moduler. Merk at registrering av en dekorasjon ikke administrerer livssyklusen for bilder i disse dekorasjonene. Din applikasjon kan bestemme hvordan disse bildene skal administreres. For eksempel kan JFace-bilderegisteret brukes til å registrere og administrere bildets livssyklus. Alternativt kan applikasjonen ønske å opprette bildet på bestiling og avhende det når det ikke lenger trengs. Javadoc for registreringsmetodene i FieldDecorationRegistry forklarer de forskjellige måtene som bilder kan spesifiseres på ved registrering av en dekorasjon.

Registrering av dekorasjoner i feltdekorasjonsregisteret kan også forenkle utformingsprosessen ved blanding av dekorerte (og ikke-dekorerte) felt. Som standard vil et dekorert felt undersøke feltdekorasjonsregisteret for å fastslå maksimal bredde for en dekorasjon og sikre at alle dekorasjoner bruker denne bredden. Det betyr at alle dine dekorerte felt vil bli riktig justert, uansett bredden på en bestemt dekorasjon. For å justere ikke-dekorerte felt kan du bruke protokollen FieldDecorationRegistry til å få tilgang til bredden til den største dekorasjonen og opprette nødvendig innrykk.

...
// Opprett et tekstfelt
Text text = new Text(parent, SWT.BORDER);
text.setText("litt tekst");
// Definer layoutdata
GridData data = new GridData();
data.horizontalAlignment = SWT.FILL;
data.horizontalIndent = FieldDecorationRegistry.getDefault().getMaximumDecorationWidth();
text.setLayoutData(data); 
...

Selv om felthjelpstøtten ikke dikterer hvordan dekorasjoner skal sendes, definerer registeret også standarddekorasjoner som kan brukes av applikasjoner til å vise enkelte statusen for et felt. For eksempel bruker følgende snutt en standarddekorasjon for nødvendige felt:

...
// Opprett et dekorert felt med en obligatorisk feltdekorasjon
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);
...

Innholdsforslag

I tillegg til å annotere felt med dekorasjoner kan applikasjoner komme med innholdsforslag som aktiverer en forslagshurtigmeny for et felt. Du kan installere en ContentProposalAdapter vilkårlig kontroll for å besørge denne virkemåten. Snutten nedenfor installerer en innholdsforslagsadapter på en tekstkontroll. Merk at denne tekstkontrollen kan være en kontroll opprettet direkte av applikasjonen eller en som kommer fra et dekorert felt.

...
autoActivationCharacters = new char[] { '#', '(' };
keyStroke = KeyStroke.getInstance("Ctrl+Space");
// anta at myTextControl allerede er opprettet
ContentProposalAdapter adapter = new ContentProposalAdapter(
	myTextControl, new TextContentAdapter(), 
	new SimpleContentProposalProvider(new String [] {"ProposalOne", "ProposalTwo", "ProposalThree"}),
	keyStroke, autoActivationCharacters);

For å hente og definere innholdet i kontrollen når brukeren velger et forslag i hurtigmenyen, må adapteren suppleres med en forekomst av IControlContentAdapter, som kan hente og definere innholdet i en bestemt type kontroll. For tekstfelt kan du bruke klassen TextContentAdapter. Du har imidlertid fleksibilitet til å implementere IControlContentAdapter for å bruke innholdskontrolladapteren med enhver type kontroll.

Når du oppretter en innholdsforslagsadapter, må du også prøve å oppgi en forekomst av IContentProposalProvider, som selve forslagene hentes fra. Denne leverandøren er ansvarlig for å returnere en rekke innholdsforslag. Selve forslagene oppgis som forekomster av IContentProposal, som etiketten og innholdet i forslaget kan hentes fra, i tillegg til andre opplysninger som f.eks. en detaljert beskrivelse av forslaget.

I eksempelet ovenfor brukes SimpleContentProposalProvider. Denne leverandøren defineres ved å oppgi en enkel rekke strenger som innholdsforslag. Den enkle leverandøren implementerer den nødvendige protokollen for å tilordne hver enkelt streng til den forventede IContentProposal. Fleksibiliteten til IContentProposalProvider gjør det mulig for deg å implementere en forslagsleverandør med avanserte funksjoner, som f.eks. filtrering av forslag basert på kontrollens innhold, oppgivelse av forklarende etiketter i hurtigmenyen i stedet for det faktiske innholdet som skal settes inn, og oppgivelse av forventet markørposisjon etter at et forslag er satt inn. Se Field Assist Example og søk etter implementerere for IContentProposalProvider for avansert bruk.

Konfigurere en innholdsforslagsadapter

Vi har sett at den grunnleggende definisjonen for en innholdsforslagsadapter inkluderer kontrollen som forslagene gis for, innholdsadapter som brukes til å endre innholdet i kontrollen, og forslagsleverandøren som definerer listen over forslag i hurtigmenyen. I tillegg til disse grunnleggende tingene er det mange måter å konfigurere forslagsadapter på:

Med felthjelpeksempelet kan du konfigurere disse forskjellige alternativene i eksempelpreferansene og prøve ut de forskjellige kombinasjonene. For eksempel kan adapteren konfigureres slik at det aktiveres eksplisitt med et tasttrykk og setter inn forslagsinnholdet i kontrollen, slik at den virker omtrent som tekstredigeringsprogrammets hurtigmeny. Eller den kan konfigureres uten et eksplisitt tasttrykk, autoaktiveringstegn og innholdserstatning, slik at virkemåten er mer som for innskrivingsfullføringen i nettleserens URL- eller søkefelt. Se javadoc for mer spesifikke opplysninger om hver av disse metodene og hvordan de virker sammen.

Arbeidsbenkens felthjelp

Felthjelpstøtte på JFace-nivå gir applikasjonen masse fleksibilitet når det gjelder å bestemme hvordan felt dekoreres og forslag vises for feltinnhold. Dette er ønskelig for frittstående JFace-applikasjoner eller frittstående Rich Client-applikasjoner. Dersom applikasjonen er beregnet på å integreres med andre plugin-moduler, f.eks. Eclipse SDK eller tredjeparts-plugin-moduler, vil du sannsynligvis ønske å bruke felthjelpstøtten på en måte som er i samsvar med andre plugin-moduler. Arbeidsbenken definerer funksjonsklasser som bruker felthjelp til bestemte typer interaksjoner.

For eksempel oppretter klassen ContentAssistField et felt som inkluderer en lyspæredekorasjon som forteller brukeren at innholdshjelp er tilgjengelig. Den konfigurerer også en innholdsforslagsadapter for innholdshjelpens stilinnsetting. Endelig besørger den en referanse for innholdshjelpkommandoen på arbeidsbenknivå, slik at hurtigmenyen for innholdsforslag åpnes når brukeren aktiverer tasttrykket eller utløsersekvensen som er oppgitt i arbeidsbenkens tastbindinger. Se org.eclipse.ui.fieldassist-pakken for nærmere detaljer om disse funksjonsklassene.

Denne pakken forventes å utvikle seg etter hvert som arbeidsbenken utvider sin bruk av felthjelp og standardiserer bruken av dekorasjoner for visse felttilstander.