Fälthjälp

En användare förväntas ofta tillhandahålla textinformation i ett enkelt fält, till exempel ett textfält eller en kombinationsruta. Trots att den programkod som finns i de här fälten i allmänhet är mycket enklare än den kod som finns i komplexa gränssnittskontroller, till exempel tabeller eller träd, är de här "enkla" fälten ofta mer krävande för användaren. Användaren måste identifiera vilka fält som måste ha innehåll, om ett fält har giltigt innehåll och vilka alternativ som förväntas. JFace-funktionerna för fälthjälpen tillhandahåller klasser som underlättar inmatning för användaren.

Paketet org.eclipse.jface.fieldassist ger två typer av hjälp. Funktioner för dekorerade fält gör det möjligt att lägga till bilddekorationer som tipsar användaren om status för ett visst fält. Funktioner för innehållsförslag gör det möjligt att lägga till hjälpsnabbmenyer med innehållsalternativ för användaren.

Dekorerade fält

Med hjälp av dekorerade fält kan du placera bilddekorationer bredvid fält som definieras i ett fönster eller en dialogruta. Dekorationer kan placeras nära ett av hörnen i ett fält. På samma sätt som visningsprogram används dekorerade fält till att lägga till funktioner till en SWT-kontroll och samtidigt ge åtkomst till den underliggande kontrollen. Med hjälp av API:t för DecoratedField kan du lägga till, dölja och visa dekorationer bredvid ett fält. Åtkomst till den underliggande kontrollen tillhandahålls så att du kan använda det befintliga API:t för SWT till att ändra den underliggande kontrollen, till exempel ange innehåll, färg eller teckensnitt för den.

Skapa ett dekorerat fält

Utifrån sett fungerar ett dekorerat fält som en enkel kontroll. Internt använder dekorerade fält en sammansatt kontroll till att hantera layouten för fältet och dess dekorationer. För det mesta spelar det här inte någon roll för klienttillämpningen. Det innebär dock att det dekorerade fältet i själva verket måste skapa kontrollen. Vi tar det här kodstycket som exempel, där en tillämpning skapar en textkontroll i en av dialogrutorna till tillämpningen:

...
// Skapa ett textfält
Text text = new Text(parent, SWT.BORDER);
text.setText("some text"); 
...

Om det här fältet ska dekoreras skapas det på det här sättet:

...
// Skapa ett dekorerat fält för en textkontroll
DecoratedField field = new DecoratedField(parent, SWT.BORDER, new TextControlCreator());
Text text = (Text)field.getControl();
text.setText("some text");
...

Samma överordnade objekt och formatbitar som skulle användas till att skapa den grundläggande kontrollen används också till att skapa ett dekorerat fält. Den främsta skillnaden i koden är att en förekomst av IControlCreator tillhandahålls som skapar den specifika typen av kontroll som önskas i fältet. För textfält kan du använda klassen TextControlCreator till att skapa kontrollen. Du kan även välja att implementera IControlCreator om du vill skapa andra typer av kontroller i fältet, till exempel en rotationsruta eller skala.

Använda dekorationer

När du har skapat ett dekorerat fält kan du lägga till dekorationer till det, på en av fyra platser. SWT-platskonstanter används till att ange var dekorationen ska placeras. Om du vill lägga till en dekoration måste du ange en FieldDecoration som definierar bilden för dekorationen och (valfritt) beskrivande text som visas när användare placerar markören på dekorationen.

...
// Skapa en fältdekoration och lägg till den till fältet
Image image = JFaceResources.getImage("myplugin.specialimage");
FieldDecoration mySpecialDecoration = new FieldDecoration(image, "This field is special");
field.addFieldDecoration(mySpecialDecoration, SWT.TOP | SWT.LEFT, false);
...

Den booleska parametern används till att ange om dekorationen ska visas endast när fokus ligger på kontrollen eller hela tiden. I det senare fallet visas dekorationen hela tiden. Det kan dock finnas tillfällen då dekorationen ska döljas eller visas. Med följande kodstycke döljs en dekoration som redan har skapats.

...
// Något har inträffat som gör att jag vill dölja dekorationen
field.hideDecoration(mySpecialDecoration);
...

Om bilden eller beskrivningen för dekorationen uppdateras bör fältet informeras om det så att dekorationen kan ritas om.

...
// Något har gjort fältet speciellt
mySpecialDecoration.setDescription("This field is extra-special");
field.updateDecoration(mySpecialDecoration);
...

Skapa layout för dekorerade och ej dekorerade fält

När du skapar layout för ett dekorerat fält i en dialogruta eller ett fönster bör du skapa layout för fältets layoutkontroll och inte för den underliggande enkla kontrollen. Kontrollera koden för att skapa en textkontroll igen. När du skapar layout för en textkontroll anger tillämpningen layoutdata för kontrollen.

...
// Skapa ett textfält
Text text = new Text(parent, SWT.BORDER);
text.setText("some text");
// Ange layoutdata
GridData data = new GridData(IDialogConstants.ENTRY_FIELD_WIDTH, SWT.DEFAULT);
text.setLayoutData(data); 
...

När du skapar layout för ett dekorerat fält ska tillämpningen ange layoutdata för layoutkontrollen för fältet. Beroende på den önskade layouten kan det hända att storleken på fältet måste justeras efter storleken på dekorationen.

...
// Skapa ett dekorerat fält för en textkontroll
DecoratedField field = new DecoratedField(main, SWT.BORDER, new TextControlCreator());
Text text = (Text)field.getControl();
text.setText("some text");
// Ange layoutdata
GridData data = new GridData(IDialogConstants.ENTRY_FIELD_WIDTH + 
   FieldDecorationRegistry.getDefault().getMaximumDecorationWidth(), SWT.DEFAULT);
field.getLayoutControl().setLayoutData(data); 
...

Det är inte nödvändigt att endast använda dekorerade fält i en viss dialogruta eller fönster för att fälthjälpen ska fungera. Layouten för fönstret kan bli en aning mer komplicerad när dekorerade fält blandas med enkla kontroller. Om du vill justera dekorerade fält och ej dekorerade fält måste du ta hänsyn till det indrag som skapades av dekorationsbredden. Bredden på dekorationen är helt enkelt bredden på bilden för den. Layouten kan dock bli mer komplicerad om du använder dekorationer med olika bredd. I så fall kan du göra den enklare genom att registrera alla dekorationerna i FieldDecorationRegistry.

Registrering av fältdekorationer

Registret för fältdekorationer gör det möjligt att registrera och visa fältdekorationer med hjälp av ett sträng-ID. Det är ett praktiskt sätt att referera till dekorationer som används i tillämpningen. Du kan välja att definiera ett API där dekorations-ID:n visas om du vill att de ska vara tillgängliga för andra insticksprogram. Lägg märke till att om du registrerar dekorationer så hanteras inte livscykeln för bilderna i de dekorationerna. Du kan ange hur bilderna hanteras via tillämpningen. Till exempel kan JFace-bildregistret användas till att registrera och hantera bildens livscykel. Alternativt kan tillämpningen skapa bilden på begäran och kassera den när den inte längre krävs. I javadoc för registreringsmetoderna i FieldDecorationRegistry förklaras de olika sätt som bilder kan anges när du registrerar en dekoration.

När du registrerar dekorationerna i registret för fältdekorationer kan du också förenkla layoutprocessen när du blandar dekorerade (och ej dekorerade) fält. När en dekoration skapas görs som standard en kontroll av största tillåtna bredd för dekorationen i registret för fältdekorationer. Den bredd som används för dekorationen används för alla dekorationer. Det innebär att alla dekorerade fält justeras på rätt sätt, oavsett bredden på enskilda dekorationer. Om du vill justera ej dekorerade fält kan du använda protokollet FieldDecorationRegistry till att visa bredden för den största dekorationen och skapa det indrag som krävs.

...
// Skapa ett textfält
Text text = new Text(parent, SWT.BORDER);
text.setText("some text");
// Ange layoutdata
GridData data = new GridData();
data.horizontalAlignment = SWT.FILL;
data.horizontalIndent = FieldDecorationRegistry.getDefault().getMaximumDecorationWidth();
text.setLayoutData(data); 
...

Även om funktionerna för fälthjälp inte dikterar hur dekorationer ska användas innehåller registret även standarddekorationer som kan användas av tillämpningar till att visa vissa lägen för ett fält. Exempel: Följande kodstycke använder en standarddekoration för obligatoriska fält:

...
// Skapa ett dekorerat fält med en dekoration för obligatoriskt fält
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);
...

Innehållsförslag

Förutom att lägga till dekorationer i fält kan du med hjälp av tillämpningar tillhandahålla en innehållsförslagshjälp som aktiverar en listruta med förslag för ett fält. Du kan installera en ContentProposalAdapter för valfri kontroll om du vill tillhandahålla den funktionen. Följande kodstycke installerar en innehållsförslagsadapter för en textkontroll. Lägg märke till att den här textkontrollen kan vara en kontroll som skapats direkt av tillämpningen eller en som hämtats från ett dekorerat fält.

...
autoActivationCharacters = new char[] { '#', '(' };
keyStroke = KeyStroke.getInstance("Ctrl+Space");
// anta att myTextControl redan har skapats på något sätt
ContentProposalAdapter adapter = new ContentProposalAdapter(
	myTextControl, new TextContentAdapter(), 
	new SimpleContentProposalProvider(new String [] {"ProposalOne", "ProposalTwo", "ProposalThree"}),
	keyStroke, autoActivationCharacters);

För att innehållet för kontrollen ska hämtas och anges när användaren väljer ett förslag i listrutan måste adaptern tillhandahållas med en förekomst av IControlContentAdapter, som kan hämta och ange innehållet för en viss typ av kontroll. För textfält kan du använda klassen TextContentAdapter. Du kan även välja att implementera IControlContentAdapter om du vill använda innehållsförslagsadaptern med andra typer av kontroller.

När du skapar en innehållsförslagsadapter måste du även ange en förekomst av IContentProposalProvider som själva förslagen hämtas från. Den här leverantören ansvarar för att returnera en mängd innehållsförslag. Själva förslagen anges som förekomster av IContentProposal, som tillhandahåller etiketten och innehållet för förslaget och övrig information, till exempel en detaljerad beskrivning av förslaget.

I exemplet ovan används SimpleContentProposalProvider. Den här leverantören definieras genom att en enkel uppsättning strängar anges som innehållsförslag. Den enkla leverantören implementerar den kontroll som krävs för att avbilda varje sträng till det förväntade IContentProposal. Tack vare flexibiliteten hos IContentProposalProvider kan du implementera en förslagsleverantör med avancerade funktioner, till exempel funktioner för att filtrera förslag baserat på kontrollens innehåll, tillhandahålla förklarande etiketter i listrutan i stället för det faktiska innehåll som infogas och ange den förväntade markörspositionen efter att ett förslag har infogats. Kontrollera fälthjälpsexemplet och sök efter implementeringsfunktioner för IContentProposalProvider för avancerad användning.

Konfiguration av en innehållsförslagsadapter

I den grundläggande definitionen av en innehållsförslagsadapter ingår alltså den kontroll som förslagen ska användas för, den innehållsadapter som används till att ändra innehållet för kontrollen och den förslagsleverantör som definierar listan med förslag för listrutan. Förutom de här grundläggande elementen kan en innehållsförslagsadapter kan konfigureras på många olika sätt:

Med hjälp av Field Assist Example kan du konfigurera de här olika alternativen i exempelinställningarna och prova dig fram med de olika kombinationerna. Till exempel kan adaptern konfigureras så att den anropas explicit med en tangent och innehållsförslaget infogas i kontrollen, vilket gör att den fungerar på liknande sätt som innehållshjälpen för textredigering. Eller så kan den konfigureras utan explicit tangent, autoaktiveringstecken och innehållsersättning, så att den fungerar mer som funktionen för automatisk ifyllning i webbläsaradresser eller sökfält. Mer specifik information om var och en av de här metoderna och hur de fungerar tillsammans finns i javadoc.

Fälthjälp i arbetsmiljön

Funktioner för fälthjälp på JFace-nivå ger stor flexibilitet för din tillämpning vad gäller hur fält dekoreras och förslag för fältinnehålls visas. Det är önskvärt för fristående JFace-tillämpningar och Rich Client-tillämpningar. Om tillämpningen är ämnad att integreras med andra insticksprogram, till exempel Eclipse SDK eller tredjepartsinsticksprogram, är det en god idé att använda funktionerna för fälthjälp på ett sätt som överensstämmer med andra insticksprogram. I arbetsmiljön definieras verktygsklasser där fälthjälp används för specifika typer av interaktioner.

Till exempel skapar klassen ContentAssistField ett fält med en glödlampsdekoration som anger att innehållshjälp är tillgänglig. Den konfigurerar även en innehållsförslagsadapter för infogning av format för innehållshjälp. Slutligen tillhandahåller den en hanterare för innehållshjälpkommandon på arbetsmiljönivå så att listrutan med innehållsförslag öppnas när användaren trycker på den aktuella tangenten eller utlöser den sekvens som angetts i nyckelbindingarna för arbetsmiljön. Mer information om de här verktygsklasserna finns i avsnittet om paketet org.eclipse.ui.fieldassist.

Det här paketet förväntas utvecklas allt eftersom arbetsmiljön expanderar användningen av fälthjälpen och standardiserar användningen av dekorationer för vissa fältlägen.