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.
Funzioni illustrate nell'editor di esempio
-
Evidenziazione della sintassi
-
Assistente ai contenuti sensibile al tipo di contenuti (JavaDoc e codice Java)
-
Comunicazione tra le funzioni di struttura del contenuto e l'editor (ad esempio, la selezione delle funzioni di struttura del contenuto aggiunge l'intervallo di evidenziazione dell'editor)
-
Due diverse modalità di presentazione
-
Segnalazione dell'intervallo di evidenziazione mediante un indicatore di intervallo visivo
-
Limitazione dell'editor alla visualizzazione esclusiva di testo all'interno dell'intervallo di evidenziazione (ad esempio, la visualizzazione di un singolo metodo di una classe Java)
-
Gestione degli indicatori
-
Condivisione dei documenti
Funzioni non illustrate
-
Formattazione dei contenuti
-
Riconciliazione dinamica della pagina di struttura dei contenuti
Esecuzione dell'editor di esempio
-
Creare un progetto
-
Creare un file con estensione file ".jav" nel progetto appena creato.
L'editor di esempio Java verrà aperto automaticamente.
-
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 e i tag JavaDoc
sono colorati in modo diverso.
-
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 verde 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.
-
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.
L'utilizzo previsto di suggerimenti sui contenuti consente 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 è visibile nel suggerimento sui contenuti. All'interno del codice Java regolare, l'editor di esempio propone sempre tutte le parole chiave Java.
-
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.
-
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.
-
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".
L'utilizzo di questa funzione è previsto, ad esempio, per le visualizzazioni di un singolo metodo.
-
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.
-
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.
-
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.
-
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 attivamente 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.
-
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à visualizzata 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.
-
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 di commenti su più righe, dei commenti JavaDoc e così via. È
necessario assicurarsi che il fornitore di documenti sia impostato su ogni
documento prodotto dal fornitore stesso.
-
Determinare quali plug-in del visualizzatore origine è necessario fornire. Tra
gli altri plug-in supportati vi sono strategie di rientro automatico, strategie di doppio clic, formatter 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.
-
Creare per tutti i plug-in 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 di contenuto che costituisce un elemento del sottoinsieme selezionato
rappresenteranno, ad esempio, evidenziazioni della sintassi. È necessario implementare le estensioni per ciascun tipo. Vedere, nell'editor di esempio, JavaDamagerRepairer e JavaDocDamagerRepairer.
-
Creare una configurazione del visualizzatore origine utilizzando i plug-in e le estensioni creati in precedenza. Vedere JavaSourceViewerConfiguration nell'editor di esempio.
-
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.
-
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.
-
Estendere il file di configurazione XML del plug-in 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 viene organizzato in quattro pacchetti:
-
org.eclipse.ui.examples.javaeditor contiene tutte le classi specifiche dell'editor.
-
org.eclipse.ui.examples.javaeditor.java contiene tutti i plug-in del visualizzatore origine specifico di Java, come ad esempio JavaDamagerRepairer, e lo strumento di suddivisione dei documenti specifico di Java.
-
org.eclipse.ui.examples.javaeditor.javadoc contiene, invece, tutti i plug-in del visualizzatore origine specifico di JavaDoc, come ad esempio JavaDocDamagerRepairer.
org.eclipse.ui.examples.javaeditor.util contiene, infine, le classi di convenienza condivise dagli altri tre pacchetti.