Esempio - Editor Java

Introduzione

L'esempio dell'editor Java illustra le funzioni standard disponibili per gli editor di testo personalizzati.  Mostra, inoltre, come  registrare un editor per un'estensione file (in questo caso .jav) e come definire un fornitore di documenti personalizzato che possa essere utilizzato da tale editor. Tale esempio vale solo a scopo illustrativo. Il supporto di modifica Java viene fornito dagli  strumenti Java di Eclipse.

Il codice di questo esempio si trova nel plugin org.eclipse.ui.examples.javaeditor. Per visualizzare il codice si consiglia di importare il plugin nello spazio di lavoro.

Funzioni illustrate nell'editor di esempio

Funzioni non illustrate

Esecuzione dell'editor di esempio Java

  1. Creare un progetto
  2. Creare un file con estensione file ".jav" nel progetto appena creato. L'editor di esempio Java verrà aperto automaticamente.
  3. Inserire il codice Java. Questo codice è colorato dinamicamente. L'editor di esempio presenta in diversi colori i seguenti elementi di linguaggio: i commenti su più righe, i commenti su una sola riga, le parole riservate del linguaggio Java, le costanti di stringa e di carattere, il codice Java regolare e i commenti su più righe che seguono le regole Javadoc. All'interno di tali commenti Javadoc, le parole chiave (in verde) e i tag HTML (in grigio) di Javadoc sono colorati in modo diverso.
  4. Aprire un nuovo commento su più righe Java inserendo "/*" all'esterno del commento. Tutte le parole comprese tra "/*" e la prima occorrenza di "*/" o tra "/*" e la fine del testo cambiano colore e diventano rosse. Aggiungere un altro "*". L'intervallo rosso diventa nero in quanto si ritiene che il commento regolare su più righe adesso contenga Javadoc. Richiamare l'assistente al codice mediante CTRL-SPAZIO. La funzione dell'assistente ai contenuti consiste nell'offrire un supporto all'utente per la scrittura del codice. Quando viene richiamato, l'assistente ai contenuti elencherà tutti i completamenti validi possibili per la posizione di chiamata. All'interno di Javadoc, l'editor di esempio propone sempre tutte le parole chiave Javadoc.
  5. Richiamare, all'esterno di un commento Java, il suggerimento sui contenuti mediante la pressione dei tasti CTRL+MAIUSC+SPAZIO. Verranno elencate cinque proposte. Sceglierne una e premere INVIO. Al di sopra della riga corrente che visualizza la proposta selezionata, verrà visualizzata una piccola finestra mobile rossa. I suggerimenti sui contenuti sono utilizzati per consentire all'utente di esprimere il proprio intento (ad esempio su come immettere una chiamata di metodo) e presentare informazioni contestuali che lo guidino nell'effettuare tale operazione. Nell'editor di esempio, la proposta per cinque caratteri validi nella posizione di chiamata iniziale. Durante la visualizzazione del suggerimento sui contenuti, richiamare l'assistente ai contenuti mediante CTRL+SPAZIO. L'assistente ai contenuti, richiamato in tale situazione, agevolerà l'esecuzione da parte dell'utente dell'intento dichiarato che è ancora visibile nel suggerimento sui contenuti. All'interno del codice Java regolare, l'editor di esempio propone sempre tutte le parole chiave Java.
  6. Salvare il codice Java. Il salvataggio aggiorna le funzioni di struttura del contenuto. Tali funzioni contengono dieci voci, ciascuna delle quali rappresenta uno dei dieci segmenti di uguali dimensioni del codice Java all'interno dell'editor. Si è scelto questo stile di struttura dei contenuti per mostrare che la semantica degli intervalli di evidenziazione può essere definita in modo arbitrario. Vedere i passi successivi.
  7. Selezionare una delle voci delle funzioni di struttura del contenuto. Le righe corrispondenti vengono contrassegnate con una barra blu nel righello verticale sinistro dell'editor.
  8. Passare, a questo punto, alla modalità di presentazione segmentata dell'editor Java. Per effettuare questa operazione, assicurarsi che l'editor sia attivo e premere il pulsante sulla barra degli strumenti del desktop con descrizione a comparsa "Abilita/Disabilita visualizzatore origine segmentata".  Questa funzionalità viene utilizzata per viste di metodo singolo e funzioni simili.
  9. Selezionare una voce diversa nelle funzioni di struttura del contenuto. Adesso l'editor visualizzerà soltanto il segmento selezionato. Deselezionando la voce nelle funzioni di struttura del contenuto, verrà visualizzato di nuovo il codice Java completo.
  10. Selezionare una voce nelle funzioni di struttura del contenuto, scegliere una frazione del testo visibile e aggiungere un'attività relativa alla selezione effettuata. L'attività verrà visualizzata nell'elenco attività. Modificare il codice visibile. Selezionare, nell'elenco attività, l'attività creata in precedenza e premere il pulsante "Vai al file". L'attività verrà selezionata nell'area visibile, includendo anche le modifiche applicate in precedenza.
  11. Selezionare un'altra voce nelle funzioni di struttura del contenuto. Visualizzare nell'elenco attività l'attività aggiunta in precedenza. L'intervallo di evidenziazione dell'editor viene ingrandito automaticamente per racchiudere l'intervallo dell'attività visualizzata.
  12. Aprire un nuovo spazio di lavoro. All'interno di questo, aprire un editor Java per lo stesso file come nello spazio di lavoro originale. Modificare il contenuto dell'editor. Ritornare allo spazio di lavoro originale. L'editor visualizzerà le modifiche apportate nell'altro spazio di lavoro. I due editor che visualizzano lo stesso file sono collegati.

Criteri per la creazione di editor di testo personalizzati

Per sviluppare un editor di testo personalizzato, di solito sono necessari i passaggi riportati di seguito.
  1. Creare un fornitore di documenti. Un fornitore di documenti (vedere IDocumentProvider) produce e gestisce documenti (vedere IDocument) che contengono una rappresentazione testuale degli elementi di input dell'editor. È importante per determinare come verrà eseguita la conversione di un elemento in una rappresentazione testuale e per decidere se il fornitore di documenti dovrà essere condiviso o meno tra più editor. Vedere la classe FileDocumentProvider nell'editor di esempio Java.
  2. Creare uno strumento di suddivisione dei documenti. Questo strumento (vedere IDocumentPartitioner) divide un documento in aree separate e assegna a ogni area un tipo di contenuto non incluso nell'insieme dei tipi di contenuto da esso stesso predefiniti. Il partizionamento dei documenti deve essere aggiornato per ogni modifica apportata ai documenti. Vedere la classe JavaPartitioner nell'editor di esempio Java. JavaPartitioner determina le aree dei tipi "commenti su più righe", "commenti Javadoc" e "altri". È necessario assicurarsi che il fornitore di documenti sia impostato su ogni documento prodotto dal fornitore stesso.
  3. Determinare quali plugin del visualizzatore origine è necessario fornire. Tra gli altri plugin supportati vi sono strategie di rientro automatico, strategie di doppio clic, programma di formattazione di contenuti e utilità di sincronizzazione delle presentazioni di testo. La descrizione che segue si limiterà all'utilità di sincronizzazione delle presentazioni di testo (vedere IPresentationReconciler). Nell'editor di esempio Java, l'utilità di sincronizzazione delle presentazioni di testo viene utilizzata per implementare l'evidenziazione della sintassi.
  4. Creare per tutti i plugin del visualizzatore origine le estensioni adeguate a ogni tipo di contenuto supportato. Come visto sopra, lo strumento di suddivisione dei documenti definisce i tipi di contenuto supportati. L'implementazione predefinita di IPresentationReconciler supporta, quali estensioni, IPresentationDamagers e IPresentationRepairers. Tali estensioni sono considerate specifiche per un determinato tipo di contenuto. Quindi, per disporre di un editor personalizzato, l'utente deve innanzitutto selezionare un sottoinsieme dei tipi di contenuto supportati. Le aree di un tipo nel sottoinsieme selezionato rappresenteranno, ad esempio, evidenziazioni della sintassi. È necessario implementare le estensioni per ciascun tipo. Vedere, nell'editor di esempio, JavaDamagerRepairer e JavaDocDamagerRepairer.
  5. Creare una configurazione del visualizzatore origine utilizzando i plugin e le estensioni creati in precedenza. Vedere JavaSourceViewerConfiguration nell'editor di esempio.
  6. Personalizzare la classe TextEditor o AbstractTextEditor con lo strumento di suddivisione dei documenti sviluppato e la configurazione del visualizzatore origine. Aggiungere o sostituire le azioni e adattare la costruzione del menu di scelta rapida dell'editor. Nella versione effettiva tale personalizzazione deve essere eseguita in una sottoclasse. Vedere JavaEditor nell'editor di esempio.
  7. Impostare un appropriato contributor della barra delle operazioni, che fornisca alla barra degli strumenti e ai menu del desktop operazioni relative all'editor. Vedere JavaActionContributor nell'editor di esempio.
  8. Estendere il file di configurazione XML del plugin dell'editor, in modo che l'editor registri un insieme specifico di estensioni file nel punto di estensione dell'editor predefinito. Impostare il contributor della barra delle operazioni anche sul file XML. Vedere il plugin.xml di questo esempio.

Organizzazione del codice dell'esempio

Il codice dell'esempio di editor Java viene organizzato in quattro pacchetti: