Difference between revisions of "EN/Documentation/BASIC Guide/Editing Text Documents"

Revision as of 18:21, 25 June 2009

Template:EN/Documentation/BASICGuideTOC/v2

Nella sezione precedente è stata presentata una serie di opzioni per la modifica dei documenti di testo, concentrandosi sui servizi com.sun.star.text.TextPortion e com.sun.star.text.Paragraph, che garantiscono l'accesso alle parti dei paragrafi nonché ai paragrafi stessi. Questi servizi sono idonei per le applicazioni in cui si deve modificare il contenuto di un testo in un unico passaggio, tramite l'uso di un ciclo. Ciò non è tuttavia sufficiente per molti problemi. Apache OpenOffice dispone del servizio com.sun.star.text.TextCursor per le operazioni più complicate, compreso lo spostamento a ritroso all'interno di un documento o lo spostamento basato su frasi e parole anziché su TextPortions.

Il TextCursor

Un TextCursor nell'API di Apache OpenOffice è paragonabile al cursore visibile utilizzato in un documento di Apache OpenOffice, ovvero contrassegna un determinato punto all'interno del documento di testo e può essere spostato in diverse direzioni tramite l'uso di comandi. Gli oggetti TextCursor disponibili in Apache OpenOffice Basic non vanno però confusi con il cursore visibile, in quanto si tratta di cose molto diverse.

Template:Documentation/Note

L'oggetto TextCursor di Apache OpenOffice, ad esempio, fornisce metodi per navigare e modificare il testo inclusi nell'oggetto Range in VBA (ad esempio, MoveStart, MoveEnd, InsertBefore, InsertAfter). Le controparti corrispondenti dell'oggetto TextCursor in Apache OpenOffice sono descritte nelle sezioni successive.

Spostamento all'interno di un testo

L'oggetto TextCursor in Apache OpenOffice Basic agisce in modo indipendente dal cursore visibile di un documento di testo. Una modifica di posizione controllata dal programma di un oggetto TextCursor non ha alcun impatto sul cursore visibile. Si possono aprire diversi oggetti TextCursor per lo stesso documento e utilizzarli in diverse posizioni reciprocamente indipendenti.

Un oggetto TextCursor viene creato utilizzando la chiamata createTextCursor:

Dim Doc As Object
Dim Cursor As Object
 
Doc = StarDesktop.CurrentComponent
Cursor = TextDocument.Text.createTextCursor()

L'oggetto Cursor così creato supporta il servizio com.sun.star.text.TextCursor, che a sua volta fornisce un'intera gamma di metodi per spostarsi all'interno dei documenti di testo. L'esempio seguente prima sposta il TextCursor di dieci caratteri verso sinistra e quindi di tre caratteri verso destra:

Cursor.goLeft(10, False)
Cursor.goRight(3, False)

Un TextCursor può evidenziare un'area completa, con un'operazione comparabile all'evidenziazione di un punto del testo tramite il mouse. Il parametro False nella chiamata di funzione precedente specifica se l'area attraversata con il movimento del cursore è evidenziata o meno. Ad esempio, il TextCursor nell'esempio seguente

Cursor.goLeft(10, False)
Cursor.goRight(3, True)

si sposta prima di dieci caratteri verso destra senza evidenziazione e poi torna indietro di tre caratteri e procede a evidenziarli. L'area evidenziata dal TextCursor inizia pertanto dopo il settimo carattere del testo e termina dopo il decimo.

Di seguito vengono elencati i metodi principali forniti dal servizio com.sun.star.text.TextCursor per lo spostamento all'interno del testo:

goLeft (Count, Expand)

Salta verso sinistra di un numero di caratteri pari a Count.

goRight (Count, Expand)

Salta verso destra di un numero di caratteri pari a Count.

gotoStart (Expand)

Passa all'inizio del documento di testo.

gotoEnd (Expand)

Passa alla fine del documento di testo.

gotoRange (TextRange, Expand)

Passa all'oggetto TextRange specificato.

gotoStartOfWord (Expand)

Passa all'inizio della parola corrente.

gotoEndOfWord (Expand)

Passa alla fine della parola corrente.

gotoNextWord (Expand)

Passa all'inizio della parola successiva.

gotoPreviousWord (Expand)

Passa all'inizio della parola precedente.

isStartOfWord ()

Restituisce True se il TextCursor è all'inizio di una parola.

isEndOfWord ()

Restituisce True se il TextCursor è alla fine di una parola.

gotoStartOfSentence (Expand)

Passa all'inizio della frase corrente.

gotoEndOfSentence (Expand)

Passa alla fine della frase corrente.

gotoNextSentence (Expand)

Passa all'inizio della frase successiva.

gotoPreviousSentence (Expand)

Passa alla fine della frase precedente.

isStartOfSentence ()

Restituisce True se il TextCursor è all'inizio di una frase.

isEndOfSentence ()

Restituisce True se il TextCursor è alla fine di una frase.

gotoStartOfParagraph (Expand)

Passa all'inizio del paragrafo corrente.

gotoEndOfParagraph (Expand)

Passa alla fine del paragrafo corrente.

gotoNextParagraph (Expand)

Passa all'inizio del paragrafo successivo.

gotoPreviousParagraph (Expand)

Passa all'inizio del paragrafo precedente.

isStartOfParagraph ()

Restituisce True se il TextCursor è all'inizio di un

paragrafo.

isEndOfParagraph ()

Restituisce True se il TextCursor alla fine di un

paragrafo.

Il testo è suddiviso in frasi sulla base dei simboli di frase. I punti, ad esempio, sono interpretati come simboli indicanti la fine delle frasi.

Il parametro Expand è un valore logico che specifica se l'area attraversata durante lo spostamento deve essere evidenziata o meno. Tutti i metodi di navigazione restituiscono inoltre un parametro che specifica se lo spostamento è riuscito o se l'azione è stata interrotta per mancanza di testo.

Di seguito vengono elencati alcuni metodi per la modifica delle aree evidenziate utilizzando un TextCursor e che supportano anche il servizio com.sun.star.text.TextCursor:

collapseToStart ()

Ripristina l'evidenziazione e posiziona il TextCursor all'inizio dell'area evidenziata in precedenza.

collapseToEnd ()

Ripristina l'evidenziazione e posiziona il TextCursor alla fine dell'area evidenziata in precedenza.

isCollapsed ()

Restituisce True se il TextCursor non copre attualmente alcuna evidenziazione.

Formattazione del testo con TextCursor

Il servizio com.sun.star.text.TextCursor supporta tutte le proprietà di caratteri e paragrafi presentate all'inizio di questo capitolo.

L'esempio seguente mostra come utilizzarle insieme a TextCursor: vaglia un documento completo e formatta in grassetto la prima parola di ogni frase.

Dim Doc As Object   
Dim Cursor As Object
Dim Proceed As Boolean
 
Doc = StarDesktop.CurrentComponent
Cursor = Doc.Text.createTextCursor
 
Do 
  Cursor.gotoEndOfWord(True)
  Cursor.CharWeight = com.sun.star.awt.FontWeight.BOLD
  Proceed = Cursor.gotoNextSentence(False)
  Cursor.gotoNextWord(False)
Loop While Proceed

L'esempio crea prima un oggetto documento per il testo che era stato appena aperto. Quindi esegue un'iterazione dell'intero testo frase per frase, evidenzia ogni prima parola e le formatta in grassetto.

Richiamo e modifica dei contenuti del testo

Se il TextCursor contiene un'area evidenziata, il testo è disponibile tramite la proprietà String dell'oggetto TextCursor. L'esempio seguente utilizza la proprietà String per visualizzare le prime parole di una frase in una finestra di messaggio:

Dim Doc As Object   
Dim Cursor As Object
Dim Proceed As Boolean
 
Doc = StarDesktop.CurrentComponent
Cursor = Doc.Text.createTextCursor
 
Do 
  Cursor.gotoEndOfWord(True)
  MsgBox Cursor.String
  Proceed = Cursor.gotoNextSentence(False)
  Cursor.gotoNextWord(False)
Loop While Proceed

Analogamente, potete modificare la prima parola di ogni frase avvalendovi della proprietà String:

Dim Doc As Object   
Dim Cursor As Object
Dim Proceed As Boolean
 
Doc = StarDesktop.CurrentComponent
Cursor = Doc.Text.createTextCursor
 
Do 
  Cursor.gotoEndOfWord(True)
  Cursor.String = "Ups"
  Proceed = Cursor.gotoNextSentence(False)
  Cursor.gotoNextWord(False)
Loop While Proceed

Se il TextCursor contiene un'area evidenziata, un'assegnazione alla proprietà String permette di sostituirla con un nuovo testo. Se non vi sono aree evidenziate, il testo viene inserito in corrispondenza dell'attuale posizione del TextCursor.

Inserimento di codici di controllo

In alcune situazioni occorre modificare non tanto il testo di un documento, quanto la sua stessa struttura. Apache OpenOffice fornisce a tal fine speciali codici di controllo, inseriti nel testo e che ne influenzano la struttura. I codici di controllo sono definiti nel gruppo di costanti com.sun.star.text.ControlCharacter. Sono disponibili i seguenti codici in Apache OpenOffice:

PARAGRAPH_BREAK

Interruzione di paragrafo.

LINE_BREAK

Testo a capo all'interno di un paragrafo.

SOFT_HYPHEN

Possibile punto di sillabazione.

HARD_HYPHEN

Punto di sillabazione obbligatorio.

HARD_SPACE

Spazio protetto che non viene né distribuito né compresso nel testo giustificato.

Per inserire i codici di controllo, è necessario non solo il cursore ma anche gli oggetti documenti di testo associati. L'esempio seguente inserisce un paragrafo dopo il ventesimo carattere di un testo:

Dim Doc As Object   
Dim Cursor As Object
Dim Proceed As Boolean
 
Doc = StarDesktop.CurrentComponent
Cursor = Doc.Text.createTextCursor
Cursor.goRight(20, False)
Doc.Text.insertControlCharacter(Cursor, _
    com.sun.star.text.ControlCharacter.PARAGRAPH_BREAK, False)

Il parametro False nella chiamata del metodo insertControlCharacter assicura che l'area attualmente evidenziata dal TextCursor permanga dopo l'operazione di inserimento. Se il parametro True viene trasmesso qui,insertControlCharacter sostituisce il testo corrente.

Ricerca di parti del testo

In molte situazioni, è necessario eseguire ricerche all'interno del testo per individuare un termine particolare e modificare il punto corrispondente. Tutti i documenti di Apache OpenOffice forniscono a tal fine una speciale interfaccia che opera sempre in conformità allo stesso principio: prima di un processo di ricerca, dovrete creare un SearchDescriptor, che definisce l'oggetto della ricerca di Apache OpenOffice all'interno del documento. Un SearchDescriptor è un oggetto che supporta il servizio com.sun.star.util. SearchDescriptor e che può essere creato utilizzando il metodo createSearchDescriptor di un documento:

Dim SearchDesc As Object
SearchDesc = Doc.createSearchDescriptor

Una volta creato il SearchDescriptor, questo riceve il testo da cercare:

SearchDesc.searchString="any text"

Per quanto riguarda la funzione espletata, il SearchDescriptor può essere paragonato alla finestra di dialogo di ricerca di Apache OpenOffice. Come in quel caso, è possibile inserire le impostazioni necessarie per la ricerca nell'oggetto SearchDescriptor.

Le proprietà sono fornite dal servizio com.sun.star.util.SearchDescriptor:

SearchBackwards (Boolean)

Esegue la ricerca nel testo a ritroso invece che in avanti.

SearchCaseSensitive (Boolean)

Prende in considerazione i caratteri maiuscoli e minuscoli durante la ricerca.

SearchRegularExpression (Boolean)

Tratta l'espressione di ricerca come un'espressione regolare.

SearchStyles (Boolean)

Ricerca il modello di paragrafo specificato all'interno del testo.

SearchWords (Boolean)

Ricerca solo parole complete.

La funzione Apache OpenOffice SearchSimilarity (o "ricerca per analogia") è disponibile anche in Apache OpenOffice Basic. Con questa funzione, Apache OpenOffice ricerca un'espressione che può essere analoga ma non esattamente uguale all'espressione di ricerca. Il numero di caratteri addizionali, eliminati e modificati per queste espressioni può essere definito singolarmente. Di seguito vengono riportate le proprietà associate al servizio com.sun.star.util.SearchDescriptor:

SearchSimilarity (Boolean)

Esegue una ricerca per analogia.

SearchSimilarityAdd (Short)

Numero di caratteri che potete aggiungere per una ricerca per analogia.

SearchSimilarityExchange (Short)

Numero di caratteri che potete sostituire come parte di una ricerca per analogia.

SearchSimilarityRemove (Short)

Numero di caratteri che potete rimuovere come parte di una ricerca per analogia.

SearchSimilarityRelax (Boolean)

Prende in considerazione tutte le regole di deviazione contemporaneamente all'espressione di ricerca.

Una volta preparato il SearchDescriptor come richiesto, è possibile applicarlo al documento di testo. I documenti di Apache OpenOffice dispongono a tal fine dei metodi findFirst e findNext:

Found = Doc.findFirst (SearchDesc)
 
Do While Found
  ' Suchergebnis bearbeiten
  Found = Doc.findNext( Found.End, Search)
Loop

L'esempio individua tutte le corrispondenze in un ciclo e restituisce un oggetto TextRange, che si riferisce al passaggio di testo reperito.

Esempio: ricerca per simili

Questo esempio mostra come ricercare in un testo la parola "viaggi" e formattare i risultati in grassetto. Viene utilizzata una ricerca per analogia in modo da reperire non solo il termine "viaggi", ma anche la forma singolare "viaggio" e le eventuali declinazioni, come "viaggiare". Le espressioni individuate differiscono di un massimo di tre lettere dall'espressione di ricerca:

Dim SearchDesc As Object
Dim Doc As Object
 
Doc = StarDesktop.CurrentComponent
SearchDesc = Doc.createSearchDescriptor
SearchDesc.SearchString="turnover"
SearchDesc.SearchSimilarity = True
SearchDesc.SearchSimilarityAdd = 2
SearchDesc.SearchSimilarityExchange = 2
SearchDesc.SearchSimilarityRemove = 2
SearchDesc.SearchSimilarityRelax = False
Found = Doc.findFirst (SearchDesc)
 
Do While Found
  Found.CharWeight = com.sun.star.awt.FontWeight.BOLD
  Found = Doc.findNext( Found.End, Search)
Loop

Template:Documentation/Note

Come nella vecchia API di Apache OpenOffice, anche nella nuova API la ricerca e la sostituzione di testo vengono eseguite utilizzando l'oggetto documento. Mentre però in precedenza esisteva un oggetto denominato SearchSettings dedicato alla definizione delle opzioni di ricerca, le nuove ricerche di oggetti vengono ora eseguite utilizzando un oggetto SearchDescriptor o ReplaceDescriptor per la sostituzione automatica del testo. Questi oggetti coprono non solo le opzioni, ma anche il testo di ricerca corrente e, se necessario, la sostituzione di testo associata. Gli oggetti descrittori vengono creati utilizzando l'oggetto documento, completati in conformità ai requisiti pertinenti e quindi nuovamente trasferiti all'oggetto documento sotto forma di parametri per i metodi di ricerca.

Sostituzione di parti del testo

Proprio come la funzione di ricerca, la funzione di sostituzione di Apache OpenOffice è disponibile anche in Apache OpenOffice Basic. La gestione delle due funzioni è identica: anche per il processo di sostituzione è necessario per prima cosa un oggetto speciale che registri i parametri del processo. È denominato ReplaceDescriptor e supporta il servizio com.sun.star.util.ReplaceDescriptor. Tutte le proprietà del SearchDescriptor descritte nel paragrafo precedente sono supportate anche da ReplaceDescriptor.. Ad esempio, durante un processo di sostituzione, potete attivare e disattivare la distinzione tra maiuscole e minuscole ed eseguire ricerche per analogia.

L'esempio seguente dimostra l'uso di ReplaceDescriptors per una ricerca all'interno di un documento di Apache OpenOffice.

Dim I As Long
Dim Doc As Object
Dim Replace As Object
Dim BritishWords(5) As String
Dim USWords(5) As String
 
BritishWords() = Array("colour", "neighbour", "centre", "behaviour", _
   "metre", "through")
USWords() = Array("color", "neighbor", "center", "behavior", _
   "meter", "thru")
 
Doc = StarDesktop.CurrentComponent
Replace = Doc.createReplaceDescriptor
 
For O = 0 To 5
  Replace.SearchString = BritishWords(I)
  Replace.ReplaceString = USWords(I)
  Doc.replaceAll(Replace)
Next n

Le espressioni di ricerca e sostituzione vengono impostate utilizzando le proprietà SearchString e ReplaceString dei ReplaceDescriptors. Il processo effettivo di sostituzione è infine implementato utilizzando il metodo replaceAll dell'oggetto documento, che sostituisce tutte le ricorrenze dell'espressione di ricerca.

Esempio: ricerca e sostituzione del testo con le espressioni regolari

La funzione di sostituzione di Apache OpenOffice è particolarmente efficace quando utilizzata assieme alle espressioni regolari. Queste ultime vi consentiranno infatti di definire un'espressione di ricerca variabile con segnaposto e caratteri speciali al posto di un valore fisso.

Le espressioni regolari supportate da Apache OpenOffice sono descritte in dettaglio nella sezione della guida in linea di Apache OpenOffice. Di seguito vengono riportati alcuni esempi:

• Un punto all'interno di un'espressione di ricerca rappresenta qualsiasi carattere. L'espressione di ricerca sh.rt può quindi rappresentare sia shirt che short.
• Il carattere ^ contrassegna l'inizio di un paragrafo. Tutte le ricorrenze del nome Peter che si trovano all'inizio di un paragrafo possono pertanto essere reperite

utilizzando l'espressione di ricerca ^Peter.

• Il carattere $ contrassegna la fine di un paragrafo. Tutte le ricorrenze del nome Peter che si trovano alla fine di un paragrafo possono pertanto essere reperite

utilizzando l'espressione di ricerca Peter$.

• Un * indica che il carattere precedente può essere ripetuto a piacere e può essere combinato con il punto come segnaposto per qualsiasi carattere. L'espressione temper.*e, ad esempio, può rappresentare sia l'espressione temperance che temperature.

L'esempio seguente mostra come rimuovere tutte le righe vuote di un documento di testo con l'ausilio dell'espressione regolare ^$:

Dim Doc As Object
Dim Replace As Object
Dim I As Long
 
Doc = StarDesktop.CurrentComponent
Replace = Doc.createReplaceDescriptor
Replace.SearchRegularExpression = True
Replace.SearchString = "^$"
Replace.ReplaceString = ""
 
Doc.replaceAll(Replace)