Assistente ai campi

Spesso un utente deve fornire informazioni di testo in un campo semplice, ad esempio una casella combinata o un campo di testo. Sebbene il codice applicazione che popola tali campi generalmente è molto più semplice del codice che popola un widget complesso come ad esempio una tabella o una struttura ad albero, tali campi "semplici" di solito implicano un ulteriore lavoro per l'utente. L'utente deve identificare quali campi richiedono contenuto, se un campo contiene un contenuto valido e quali opzioni sono previste. Il supporto dell'assistente ai campi JFace fornisce delle classi che guidano l'utente nelle attività di input.

Il pacchetto org.eclipse.jface.fieldassist fornisce assistenza in due modi. Il supporto per i campi decorati consente di includere delle decorazioni di immagini che suggeriscono all'utente lo stato di un determinato campo. Il supporto di proposta del contenuto consente di utilizzare un menu a comparsa dell'assistente ai contenuti che fornisce opzioni di contenuto per l'utente.

Campi decorati

I campi decorati consentono di inserire delle decorazioni di immagini adiacenti ai campi definiti in una finestra o in una finestra di dialogo. Le decorazioni possono essere inserite adiacenti a uno dei quattro angoli di un campo. Come molti visualizzatori, i campi decorati sono ideati per aggiungere funzionalità a un controllo SWT, fornendo l'accesso al controllo sottostante. L'API per DecoratedField consente di aggiungere, nascondere e visualizzare le decorazioni adiacenti a un campo. L'accesso al controllo sottostante viene fornito per consentire all'utente di utilizzare l'API SWT al fine di influenzare il controllo sottostante, ad esempio impostando contenuto, colore o tipo di carattere.

Creazione di un campo decorato

Dall'esterno, un campo decorato ha la stessa funzionalità di un singolo controllo. Internamente, i campi utilizzano un controllo composito per gestire il layout del campo e delle relative decorazioni. Per la maggior parte, ciò non dovrebbe interessare l'applicazione client. Tuttavia, ciò significa che il campo decorato deve eseguire la creazione effettiva del controllo. Ad esempio, considerare questo frammento, in cui un'applicazione crea un controllo di testo in una delle relative finestre di dialogo:

...
// Creare un campo di testo
Text text = new Text(parent, SWT.BORDER);
text.setText("un testo"); 
...

Per decorare questo campo, è necessario crearlo nel modo seguente:

...
// Creare un campo decorato per un controllo di testo
DecoratedField field = new DecoratedField(parent, SWT.BORDER, new TextControlCreator());
Text text = (Text)field.getControl();
text.setText("un testo");
...

Gli stessi bit parent e di stile che si utilizzano per creare il controllo di base vengono utilizzati anche per creare un campo decorato. La differenza principale nel codice sta nel fatto che viene fornita un'istanza di IControlCreator che crea il tipo specifico di controllo desiderato nel campo. Per i campi di testo, è possibile utilizzare la classe TextControlCreator per creare il controllo. Tuttavia, se si desidera, è possibile implementare IControlCreator per creare un altro tipo di controllo all'interno del campo, ad esempio una casella combinata o una casella di selezione.

Utilizzo delle decorazioni

Dopo aver creato un campo decorato, è possibile aggiungervi decorazioni in uno dei quattro punti. Le costanti di ubicazioni SWT vengono utilizzate per specificare dove inserire la decorazioni. Per aggiungere una decorazione, è necessario specificare un FieldDecoration, che definisce l'immagine per la decorazione e del testo descrittivo (facoltativo) che può essere visualizzato quando l'utente lascia scorrere il mouse sulla decorazione.

...
// Creare una decorazione di campo e aggiungerla al campo
Image image = JFaceResources.getImage("myplugin.specialimage");
FieldDecoration mySpecialDecoration = new FieldDecoration(image, "Questo campo è speciale");
field.addFieldDecoration(mySpecialDecoration, SWT.TOP | SWT.LEFT, false);
...

Il parametro booleano viene utilizzato per specificare se la decorazione deve essere visualizzata solo quando il controllo ha lo stato attivo oppure se deve essere visualizzata tutte le volte. In questo caso, la decorazione verrà visualizzata tutto il tempo. Tuttavia, potrebbero esserci altre volte in cui la decorazione deve essere nascosta o visualizzata. Il frammento di codice riportato di seguito nasconde una decorazione che è stata già creata.

...
// Si è verificato qualcosa per cui è preferibile nascondere la decorazione
field.hideDecoration(mySpecialDecoration);
...

Se l'immagine o la descrizione di una decorazione viene aggiornata, è necessario inviare una notifica al campo in modo che la decorazione possa essere ridisegnata

...
// Qualcosa ha reso questo campo extra-special
mySpecialDecoration.setDescription("Questo campo è extra-special");
field.updateDecoration(mySpecialDecoration);
...

Layout di campi decorati e non decorati

Quando si esegue il layout di un campo decorato all'interno di una finestra di dialogo o di una finestra, è necessario eseguire il layout del controllo di layout del campo, anziché del controllo semplice sottostante. Si consideri di nuovo il codice per la creazione di un controllo di testo. Quando si esegue il layout di un controllo di testo, l'applicazione imposta i dati di layout sul controllo.

...
// Creare un campo di testo
Text text = new Text(parent, SWT.BORDER);
text.setText("un testo");
// Impostare i dati di layout
GridData data = new GridData(IDialogConstants.ENTRY_FIELD_WIDTH, SWT.DEFAULT);
text.setLayoutData(data); 
...

Quando si esegue il layout di un campo decorato, l'applicazione dovrebbe consentire i dati di layout sul controllo di layout del campo. A seconda del layout desiderato, è possibile che la dimensione del campo debba essere modificata in base alla dimensione della decorazione.

...
// Creare un campo decorato per un controllo di testo
DecoratedField field = new DecoratedField(main, SWT.BORDER, new TextControlCreator());
Text text = (Text)field.getControl();
text.setText("un testo");
// Impostare i dati di layout
GridData data = new GridData(IDialogConstants.ENTRY_FIELD_WIDTH + 
   FieldDecorationRegistry.getDefault().getMaximumDecorationWidth(), SWT.DEFAULT);
field.getLayoutControl().setLayoutData(data); 
...

Il supporto assistente ai campi non richiede o presuppone l'uso di soli campi decorati all'interno di una determinata finestra o finestra di dialogo. Tuttavia, il layout della finestra potrebbe diventare un po' più complicato quando i campi decorati vengono combinati con controlli semplici. Per allineare i campi decorati e non decorati, è necessario tener conto dei rientri creati dall'ampiezza della decorazione. La larghezza di una decorazione corrisponde alla larghezza della sua immagine. Tuttavia, le cose possono complicarsi ulteriormente se si utilizzano decorazioni con larghezze differenti. In tal caso, è possibile semplificare le cose registrando tutte le decorazioni in FieldDecorationRegistry.

Registro delle decorazioni dei campi

Il Registro delle decorazioni dei campi consente di registrare e accedere alle decorazioni dei campi utilizzando un id stringa. Si tratta di un metodo molto pratico di fare riferimento alle decorazioni utilizzate all'interno dell'applicazione. È possibile scegliere di definire API che espongono gli id decorazione se si desidera renderle disponibili ad altri plugin. Si noti che registrando una decorazione non gestisce il ciclo di vita delle immagini all'interno di queste decorazioni. L'applicazione può decidere come gestire queste immagini. Ad esempio, il registro delle immagini JFace può essere utilizzato per registrare e gestire il ciclo di vita delle immagini. In alternativa, l'applicazione può creare l'immagine su richiesta ed eliminarla quando non è più necessaria. Il javadoc per i metodi di registrazione in FieldDecorationRegistry illustra i diversi modi in cui le immagini possono essere specificate quando si registra una decorazione.

La registrazione delle decorazioni nel registro delle decorazioni dei campi può anche semplificare il processo di layout quando si combinano campi decorati (e non decorati). Per impostazione predefinita, un campo decorato consulterà il registro delle decorazioni dei campi per determinare la larghezza massima di una decorazione e assicurarsi che tutte le decorazioni utilizzino questa larghezza. Ciò significa che tutti i campi decorati si allineeranno correttamente, indipendentemente dalla larghezza di una particolare decorazione. Per allineare campi non decorati, è possibile utilizzare il protocollo FieldDecorationRegistry per accedere alla larghezza della decorazione più larga e creare il rientro necessario.

...
// Creare un campo di testo
Text text = new Text(parent, SWT.BORDER);
text.setText("un testo");
// Set the layout data
GridData data = new GridData();
data.horizontalAlignment = SWT.FILL;
data.horizontalIndent = FieldDecorationRegistry.getDefault().getMaximumDecorationWidth();
text.setLayoutData(data); 
...

Sebbene il supporto assistente ai campi non indichi in che modo le decorazione dovrebbero essere utilizzate, il registro definisce anche decorazioni standard che possano essere utilizzate da applicazioni per mostrare determinati stati per un campo. Ad esempio, il seguente frammento di codice utilizza una decorazione standard per i campi richiesti:

...
// Creare un campo decorato con una decorazione di campo richiesta.
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);
...

Proposte di contenuto

Oltre ad annotare campi con decorazioni, le applicazioni possono fornire un assistente alle proposte di contenuto che attiva una finestra a comparsa contenente una proposta per un campo. È possibile installare un ContentProposalAdapter su un controllo arbitrario allo scopo di fornire questa funzionalità. Il seguente frammento di codice installa un adattatore per proposte di contenuto su un controllo di testo. Si noti che questo controllo di testo potrebbe essere un controllo creato direttamente dall'applicazione oppure da uno ottenuto da un campo decorato.

...
autoActivationCharacters = new char[] { '#', '(' };
keyStroke = KeyStroke.getInstance("Ctrl+Space");
// si presuppone che myTextControl sia stato già creato
ContentProposalAdapter adapter = new ContentProposalAdapter(
	myTextControl, new TextContentAdapter(), 
	new SimpleContentProposalProvider(new String [] {"ProposalOne", "ProposalTwo", "ProposalThree"}),
	keyStroke, autoActivationCharacters);

Allo scopo di ottenere e impostare il contenuto del controllo quando l'utente sceglie una proposta nella finestra a comparsa, l'adattatore deve disporre di un'istanza di IControlContentAdapter, che possa recuperare e impostare il contenuto di un particolare tipo di controllo. Per i campi di testo, è possibile utilizzare la classe TextContentAdapter. Tuttavia, è possibile implementare IControlContentAdapter per utilizzare l'adattatore per proposte di contenuto con un altro tipo di controllo.

Quando si crea un adattatore per proposte di contenuto, è necessario specificare anche un'istanza di IContentProposalProvider, da cui recuperare le proposte. Questo fornitore è responsabile della restituzione di un gruppo di proposte di contenuto. Le stesse proposte vengono specificate come istanze di IContentProposal, da cui è possibile ottenere l'etichetta e il contenuto della proposta, in aggiunta ad altre informazioni, come la descrizione dettagliata della proposta

Nell'esempio riportato sopra, viene utilizzato SimpleContentProposalProvider. Questo fornitore viene definito specificando un semplice gruppo di stringhe come proposte di contenuto. Il fornitore semplice implementa il protocollo necessario per associare ciascuna stringa alla IContentProposal prevista. La flessibilità di IContentProposalProvider permette di implementare un fornitore di proposte con funzioni avanzate, come il filtraggio delle proposte sulla base del contenuto del controllo, fornendo etichette descrittive nella finestra a comparsa anziché il reale contenuto che verrà inserito e specificando la posizione del cursore prevista dopo aver inserito una proposta. Vedere Esempio assistente ai campi e cercare gli implementatori di IContentProposalProvider per un uso avanzato.

Configurazione di un adattatore per proposte di contenuto

La definizione di base di adattatore per proposte di contenuto include il controllo per il quale le proposte vengono fornite, l'adattatore di contenuto utilizzato per modificare il contenuto del controllo e il fornitore di proposte che definisce l'elenco di proposte nella finestra a comparsa. Oltre a ciò, esistono molti modi in cui è possibile configurare un adattatore per proposte di contenuto:

Esempio Assistente ai campi consente di configurare queste varie opzioni nelle preferenze di esempio e provare le diverse combinazioni. Ad esempio, è possibile configurare l'adattatore in modo che venga richiamato esplicitamente con una battitura di tasti e inserisca il contenuto della proposta nel controllo, in modo che funzioni come un assistente ai contenuti di un editor di testo. Oppure, è possibile configurarlo senza una battitura di tasti esplicita, caratteri di autoattivazione e sostituzione di contenuto in modo che si comporti come la funzionalità di completamento di tipo "type-ahead" utilizzata negli URL dei browser Web o nei campi di ricerca. Per ulteriori informazioni su questi metodi e su come interagiscono tra loro, vedere il javadoc.

Assistente ai campi del workbench

Il supporto Assistente ai campi a livello JFace offre all'applicazione molta flessibilità nel determinare come decorare campi e mostrare proposte per il contenuto dei campi. Questa funzionalità è auspicabile per applicazioni JFace o applicazioni rich client autonome. Tuttavia, se l'applicazione è destinata ad essere integrata con altri plugin, come Eclipse SDK o plugin di altri produttori, probabilmente questa supporto per assistente ai campi verrà utilizzato in maniera coerente con altri plugin. Il workbench definisce le classi di utilità che utilizzano assistente ai campi per tipi di interazioni specifici.

Ad esempio, la classe ContentAssistField crea un campo che include una decorazione che raffigura una lampadina per segnalare all'utente che assistente ai contenuti è disponibile. Inoltre, configura un adattatore per proposte di contenuto per un inserimento del tipo assistente ai contenuti. Infine, fornisce un gestore per il comando di assistente ai contenuti a livello di workbench, in modo la finestra a comparsa della proposta di contenuto si apra quando l'utente richiama la battitura di tasti o una sequenza di attivazione/disattivazione specificata nell'associazione di chiavi del workbench. Vedere il pacchetto org.eclipse.ui.fieldassist per ulteriori dettagli su queste classi.

Si prevede che questo pacchetto evolva quando il workbench incrementa l'uso della funzione assistente ai campi e standardizza l'uso di decorazioni per determinati stati di campi.