Modifica dei documenti di testo

From Apache OpenOffice Wiki
Jump to: navigation, search

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. OpenOffice.org 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 OpenOffice.org è paragonabile al cursore visibile utilizzato in un documento di OpenOffice.org, 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 OpenOffice.org Basic non vanno però confusi con il cursore visibile, in quanto si tratta di cose molto diverse.

Documentation note.png La terminologia differisce da quella utilizzata in VBA: in termini di portata della funzione, l'oggetto Range di VBA può essere confrontato con l'oggetto TextCursor di OpenOffice.org ma non, come sembrerebbe suggerire il nome, con l'oggetto Range di OpenOffice.org.

L'oggetto TextCursor di OpenOffice.org, 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 OpenOffice.org sono descritte nelle sezioni successive.

Spostamento all'interno di un testo

L'oggetto TextCursor in OpenOffice.org 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. OpenOffice.org 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 OpenOffice.org:

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 OpenOffice.org 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 OpenOffice.org 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 OpenOffice.org. 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 OpenOffice.org SearchSimilarity (o "ricerca per analogia") è disponibile anche in OpenOffice.org Basic. Con questa funzione, OpenOffice.org 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 OpenOffice.org 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
Documentation note.png L'idea base della ricerca e sostituzione in OpenOffice.org è paragonabile a quella utilizzata in VBA. Entrambe le interfacce forniscono un oggetto, attraverso il quale si possono definire le proprietà di ricerca e sostituzione. Questo oggetto viene quindi applicato all'area di testo richiesta per eseguire l'azione. Mentre l'oggetto ausiliare responsabile in VBA può essere raggiunto tramite la proprietà Find dell'oggetto Range, in OpenOffice.org Basic viene creato dalla chiamata createSearchDescriptor o createReplaceDescriptor dell'oggetto documento. Persino le proprietà e i metodi di ricerca disponibili differiscono.

Come nella vecchia API di OpenOffice.org, 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 OpenOffice.org è disponibile anche in OpenOffice.org 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 OpenOffice.org.

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 OpenOffice.org è 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 OpenOffice.org sono descritte in dettaglio nella sezione della guida in linea di OpenOffice.org. 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)
Content on this page is licensed under the Public Documentation License (PDL).
Personal tools