Feltassistance

En bruger forventes ofte at angive tekstoplysninger i et enkelt felt, f.eks. et tekstfelt eller en kombinationsboks. Selvom programkoden, der udfylder disse felter, generelt er meget enklere end koden, der udfylder en kompleks widget, f.eks. en tabel eller en træstruktur, volder disse "enkle" felter normalt flere problemer for brugeren. Brugeren skal fastlægge, hvilke felter der skal udfyldes, om et felt har gyldigt indhold, og hvilke valg der forventes. JFace feltassistance indeholder klasser, der hjælper brugeren med at angive input.

Pakken org.eclipse.jface.fieldassist indeholder to former for hjælp. Understøttelse til dekorerede felter gør det muligt at inkludere billeddekorationer, der viser brugeren tip om status for et bestemt felt. Forslag til indhold gør det muligt at stille indholdsassistance til rådighed i en pop op-menu, der viser de mulige valg af indhold for brugeren.

Dekorerede felter

Dekorerede felter gør det muligt for dig at placere billeddekorationer ud for felter, der er defineret i et vindue eller en dialogboks. Dekorationer kan placeres ud for et af de fire hjørner i et felt. I lighed med fremvisere er dekorerede felter beregnet på at tilføje funktionalitet til en SWT-kontrol og samtidig give adgang til rådighed til den underliggerende kontrol. API'et til DecoratedField gør det muligt at tilføje, skjule og vise dekorationer ud for et felt. Adgang til den underliggende kontrol stilles til rådighed, så du kan bruge det eksisterende SWT API til at påvirke den underliggende kontrol, f.eks. angive dens indhold, farve eller font.

Opret et dekoreret felt

Udefra fungerer et dekoreret felt som en enkelt kontrol. Internt anvender dekorerede felter en sammensat kontrol til at administrere layoutet for et felt og dets dekorationer. For det meste skulle dette ikke betyde noget for klientprogrammet. Det betyder imidlertid, at det dekorerede felt skal udføre den faktiske oprettelse af kontrollen. Se eksemplet nedenfor med stykket, hvor et program opretter en tekstkontrol i en af sine dialogbokse:

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

For at dette felt kan dekoreres, skal det oprettes på denne måde:

...
// Opret et dekoreret felt til en tekstkontrol
DecoratedField field = new DecoratedField(parent, SWT.BORDER, new TextControlCreator());
Text text = (Text)field.getControl();
text.setText("noget tekst");
...

De samme overordnede bit og typografibit, der anvendes til at oprette basiskontrol, bruges også til at oprette et dekoreret felt. Den primære forskel i koden er, at en forekomst af en IControlCreator stilles til rådighed, der opretter en specifik slags kontrol, der ønskes i feltet. Til tekstfelter kan du bruge klassen TextControlCreator til at oprette kontrollen. Du kan imidlertid også implementere IControlCreator for at oprette enhver anden type kontrol i feltet, f.eks. en kombinationsboks eller en spinner.

Brug af dekorationer

Når et dekoreret felt er oprettet, kan dekorationer tilføjes til det ét af fire steder. SWT-placeringskonstanter anvendes til at angive, hvor dekorationer skal placeres. Hvis du vil tilføje en dekoration, skal du angive FieldDecoration, der angiver billedet for dekorationen og en (valgfri) beskrivende tekst, når brugeren placerer markøren over dekorationen.

...
// Opret en feltdekoration, og tilføj den til feltet
Image image = JFaceResources.getImage("myplugin.specialimage");
FieldDecoration mySpecialDecoration = new FieldDecoration(image, "Dette felt er specielt");
field.addFieldDecoration(mySpecialDecoration, SWT.TOP | SWT.LEFT, false);
...

Den booleske parameter anvendes til at angive, om dekorationen kun skal vises, når kontrollen er i fokus, eller om den skal vises hele tiden. I så fald vises dekorationen hele tiden. Der er imidlertid andre gange, hvor dekorationen skal skjules eller vises. Det følgende stykke skjuler en dekoration, der allerede er oprettet.

...
// Der er opstået noget, så jeg gerne vil skjule dekorationen
field.hideDecoration(minSaerligeDekoration);
...

Hvis billedet eller beskrivelsen af dekorationen opdateres, skal dette felt underrettes, så dekorationen kan gentegnes.

...
// Noget har gjort dette felt særligt specielt
minSaerligeDekoration.setDescription("Dette felt er særligt specielt");
field.updateDecoration(minSaerligeDekoration);
...

Layout af dekorerede og ikke dekorerede felter

Ved layout af dekorerede felter i en dialogboks eller et vindue, skal du foretage layout af feltets layoutkontrol i stedet for af den underliggende enkle kontrol. Iagttag igen koden for oprettelse af en tekstkontrol. Når du foretager layout af en tekstkontrol, angiver programmet layoutdata på kontrollen.

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

Ved layout af et dekoreret felt skal programmet angive layoutdata på feltets layoutkontrol. Afhængig af det ønskede layout skal størrelsen af feltet være justeret med størrelsen af dekorationen.

...
// Opret et dekoreret felt for en tekstkontrol
DecoratedField field = new DecoratedField(main, SWT.BORDER, new TextControlCreator());
Text text = (Text)field.getControl();
text.setText("noget tekst");
// Angiv layoutdata
GridData data = new GridData(IDialogConstants.ENTRY_FIELD_WIDTH + 
   FieldDecorationRegistry.getDefault().getMaximumDecorationWidth(), SWT.DEFAULT);
field.getLayoutControl().setLayoutData(data); 
...

Feltassistancen kræver ikke og antager ikke, at du kun bruger dekorerede felter inden for en bestemt dialogboks eller et vindue. Layoutet af vinduet kan dog bliver lidt mere kompliceret, hvis dekorerede felter blandes med enkle kontroller. For at justere dekorerede og ikke dekorerede felter skal du tage hensyn til den indrykning, der oprettes af dekorationsbredden. Bredden af en dekoration er simpelthen bredden af dets billede. Det kan blive mere kompliceret, hvis du bruger dekorationer med forskellig bredde. Hvis det er tilfældet, kan du forenkle tingene ved at registrere alle dekorationer i FieldDecorationRegistry.

Registreringsdatabase for feltdekorationer

Registreringsdatabasen for feltdekorationer gør det muligt at registrere og få adgang til feltdekorationer vha. en streng-id. Det er en praktisk måde at henvise til dekorationer på, der anvendes i hele programmet. Du kan vælge at angive et API, der viser dekorations-id'er, hvis du vil gøre dem tilgængelige for andre plugins. Bemærk, at registrering af en dekoration ikke administrerer billedets livscyklus inden for disse dekorationer. Programmet kan afgøre, hvordan billederne skal administreres. F.eks. kan JFace-billedregistreringsdatabasen anvendes til at registrere og administrere billedets livscyklus. Alternativt kan programmet oprette billedet efter behov og fjerne det, når der ikke længere er brug for det. Javadoc for registreringsmetoderne i FieldDecorationRegistry forklarer de forskellige måder, som billeder kan angives på, når en dekoration registreres.

Registrering af dekorationer i feltdekorationsregistreringsdatabasen forenkler også layoutprocessen, når dekorerede (og ikke dekorerede) felter blandes. Som standard vil et dekoreret felt konsultere feltdekoreringsregistreringsdatabasenfor at bestemme den maksimale bredde på dekorationen og sikre, at alle dekorationer bruger denne bredde. Det betyder, at alle dekorerede felter justeres korrekt, uanset bredden af en bestemt dekoration. Hvis du vil justere ikke dekorerede felter, kan du bruge protokollen FieldDecorationRegistry for at få adgang til bredden af den største dekoration og oprette den nødvendige indrykning.

...
// Opret et tekstfelt
Text text = new Text(parent, SWT.BORDER);
text.setText("some text");
// Angiv layoutdata
GridData data = new GridData();
data.horizontalAlignment = SWT.FILL;
data.horizontalIndent = FieldDecorationRegistry.getDefault().getMaximumDecorationWidth();
text.setLayoutData(data); 
...

Selvom feltassistancen ikke dikterer, hvordan dekorationer skal bruges, definerer registreringsdatabasen også standarddekorationer, der kan bruges af programmer til at vise visse tilstande for et felt. Følgende stykke bruger en standarddekoration til påkrævede felter:

...
// Opret et dekoreret felt med en påkrævet feltdekoration.
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);
...

Indholdsforslag

Ud over at annotere felter med dekorationer, kan programmer stille en assistance til indholdsforslag til rådighed, der aktiverer et pop op-vindue med forslag til et felt. Du kan installere en ContentProposalAdapter på en vilkårlig kontrol for at stille denne funktionsmåde til rådighed. Følgende stykke installerer en adapter for indholdsforslag på en tekstkontrol. Bemærk, at denne tekstkontrol kan være en kontrol, der er oprettet direkte af programmet, eller som er hentet fra et dekoreret felt.

...
autoActivationCharacters = new char[] { '#', '(' };
keyStroke = KeyStroke.getInstance("Ctrl+Space");
// antag, at myTextControl allerede er oprettet på en eller anden måde
ContentProposalAdapter adapter = new ContentProposalAdapter(
	myTextControl, new TextContentAdapter(), 
	new SimpleContentProposalProvider(new String [] {"ProposalOne", "ProposalTwo", "ProposalThree"}),
	keyStroke, autoActivationCharacters);

For at hente og angive indholdet af kontrollen, når brugeren vælger et forslag i pop op-vinduet, skal adapteren forsynes med en forekomst af IControlContentAdapter, der kan hente og angive indholdet af en bestemt type kontrol. Til tekstfelter kan du bruge klassen TextContentAdapter. Du har imidlertid muligheden for at implementere IControlContentAdapter, hvis du vil bruge adapteren for indholdsforslag med andre typer kontrol.

Når du opretter en adapter for indholdskontrol, skal du også angive en forekomst af IContentProposalProvider, hvorfra forslagene selv hentes. Denne udbyder er ansvarlig for at returnere et array af indholdsforslag. Forslagene selv angives som forekomster af IContentProposal, hvorfra etiketten og indholdet af forslaget kan hentes ud over andre oplysninger, f.eks. en detaljeret beskrivelse af forslaget.

I eksemplet ovenfor anvendes SimpleContentProposalProvider. Denne udbyder defineres ved at angive et enkelt array af strenge som indholdsforslag. Denne enkle udbyder implementerer den nødvendige protokol for at knytte hver streng til det forventede IContentProposal. Fleksibiliteten i IContentProposalProvider gør det muligt at implementere en forslagsudbyder med avancerede funktioner, f.eks. filtrering af forslag baseret på kontrollens indhold, der stiller forklarende etiketter i pop op-vinduer til rådighed i stedet for det aktuelle indhold, der indsættes, og som angiver den forventede markørposition, når forslaget er indsat. Der er oplysninger om avanceret anvendelse under Eksempel på feltassistance, hvis du søger efter implementorer af IContentProposalProvider.

Konfigurér en adapter for indholdsforslag

Vi har vist, at den grundlæggende definition af en adapter for indholdsforslag inkluderer kontroller, som forslagene stilles til rådighed for, indholdsadapteren, der anvendes til at ændre indholdet af kontrollen, samt den forslagsudbyder, der definerer listen med forslag i pop op-vinduet. Ud over disse grundlæggende forhold kan en adapter for indholdsforslag konfigureres på mange måder:

Eksempel på feltassistance gør det muligt at konfigurere de forskellige indstillinger i eksempelindstillingerne og prøve de forskellige kombinationer. F.eks. kan adapteren konfigureres, så den startes eksplicit med et tastanslag og indsætter indholdsforslaget i kontrollen, så adapteren fungerer ligesom indholdsassistancen i teksteditoren. Den kan også konfigureres uden et eksplicit tastanslag, auto-aktiverede tegn og indholdserstatning, så den fungerer mere som de fortløbende indtastningsformater, der anvendes i en webbroweradresse eller søgefelter. Der er flere oplysninger i Javadoc om metoderne, og hvordan de spiller sammen.

Feltassistance for arbejdsbænk

Feltassistance på JFace-niveau giver et program en masse fleksibilitet med hensyn til, hvordan felter kan dekoreres, og hvordan forslag til feltindhold vises. Det er praktisk for JFace-programmer eller enkeltstående Rich Client-programmer. Hvis programmet skal integreres med andre plugins, f.eks. Eclipse SDK eller tredjepartsplugins, kan du formentlig med fordel bruge feltassistance på en måde, der er konsistent med andre plugins. Arbejdsbænken definerer funktionsklasser, der anvender feltassistance til bestemte typer interaktioner.

F.eks. opretter klassen ContentAssistField et felt, der inkluderer en dekoration med en lyspære for at gøre brugeren opmærksom på, at der er indholdsassistance. Den konfigurerer også en adapter for indholdsassistance til indsættelse af indholdsassistancetyper. Endelig stiller den en behandler til rådighed for indholdsassistancekommandoen på arbejdsbænkniveau, så pop op-vinduet med indholdsassistance åbnes, når brugeren begynder indtastning eller udløser en sekvens, der er angivet i arbejdsbænkens tastbindinger. Der er flere oplysninger under pakken org.eclipse.ui.fieldassist om disse funktionsklasser.

Denne pakke forventes at blive udviklet, efterhånden som arbejdsbænken udvider brugen af feltassistance og standardiserer brugen af dekorationer for bestemte felttilstande.