Difference between revisions of "IT/Documentation/BASIC Guide/Structure of Text Documents"
(New page: {{DISPLAYTITLE:Struttura dei documenti di testo}} {{IT/Documentation/BASICGuideTOC/v2 |ShowPrevNext=block |ShowPrevPage=block |PrevPage=Documentation/BASIC Guide/Text Documents |NextPage=D...) |
|||
Line 19: | Line 19: | ||
== Paragrafi e parti di paragrafi== | == Paragrafi e parti di paragrafi== | ||
− | Il nucleo di un documento di testo consiste in una sequenza di paragrafi non indicizzati a cui non è attribuito alcun nome, pertanto non esiste un metodo per accedere direttamente ai singoli paragrafi. I paragrafi si possono tuttavia vagliare sequenzialmente con l'ausilio dell'oggetto <tt>Enumeration</tt> descritto in [[Documentation/BASIC Guide/API Intro|Introduzione all'API]]. In questo modo, i paragrafi possono essere modificati. | + | Il nucleo di un documento di testo consiste in una sequenza di paragrafi non indicizzati a cui non è attribuito alcun nome, pertanto non esiste un metodo per accedere direttamente ai singoli paragrafi. I paragrafi si possono tuttavia vagliare sequenzialmente con l'ausilio dell'oggetto <tt>Enumeration</tt> descritto in [[IT/Documentation/BASIC Guide/API Intro|Introduzione all'API]]. In questo modo, i paragrafi possono essere modificati. |
Quando si utilizza l'oggetto <tt>Enumeration</tt>, è necessario tenere presente il seguente scenario particolare: non restituisce solo paragrafi, ma anche tabelle (in senso stretto, in {{OOo}} Writer una tabella è uno speciale tipo di paragrafo). Prima di accedere a un oggetto restituito, dovete controllare se supporta il servizio <idl>com.sun.star.text.Paragraph</idl> per i paragrafi o il servizio <idl>com.sun.star.text.TextTable</idl> per le tabelle. | Quando si utilizza l'oggetto <tt>Enumeration</tt>, è necessario tenere presente il seguente scenario particolare: non restituisce solo paragrafi, ma anche tabelle (in senso stretto, in {{OOo}} Writer una tabella è uno speciale tipo di paragrafo). Prima di accedere a un oggetto restituito, dovete controllare se supporta il servizio <idl>com.sun.star.text.Paragraph</idl> per i paragrafi o il servizio <idl>com.sun.star.text.TextTable</idl> per le tabelle. |
Revision as of 02:59, 7 July 2009
- Struttura dei documenti di testo
- Modifica dei documenti di testo
- Molto più che semplice testo
Un documento di testo può contenere essenzialmente quattro tipi di informazioni:
- Il testo vero e proprio
- I modelli per la formattazione di caratteri, paragrafi e pagine
- Elementi non testuali quali tabelle, immagini e oggetti disegno
- Impostazioni globali per il documento di testo
La presente sezione tratta in particolare il testo e le opzioni di formattazione associate.
Contents
Paragrafi e parti di paragrafi
Il nucleo di un documento di testo consiste in una sequenza di paragrafi non indicizzati a cui non è attribuito alcun nome, pertanto non esiste un metodo per accedere direttamente ai singoli paragrafi. I paragrafi si possono tuttavia vagliare sequenzialmente con l'ausilio dell'oggetto Enumeration descritto in Introduzione all'API. In questo modo, i paragrafi possono essere modificati.
Quando si utilizza l'oggetto Enumeration, è necessario tenere presente il seguente scenario particolare: non restituisce solo paragrafi, ma anche tabelle (in senso stretto, in Apache OpenOffice Writer una tabella è uno speciale tipo di paragrafo). Prima di accedere a un oggetto restituito, dovete controllare se supporta il servizio com.sun.star.text.Paragraph per i paragrafi o il servizio com.sun.star.text.TextTable per le tabelle.
L'esempio seguente vaglia i contenuti di un documento di testo in un ciclo e utilizza un messaggio in ogni istanza tramite cui l'utente può determinare se l'oggetto in questione è un paragrafo o una tabella.
Dim Doc As Object Dim Enum As Object Dim TextElement As Object ' Create document object Doc = StarDesktop.CurrentComponent ' Create enumeration object Enum = Doc.Text.createEnumeration ' loop over all text elements While Enum.hasMoreElements TextElement = Enum.nextElement If TextElement.supportsService("com.sun.star.text.TextTable") Then MsgBox "The current block contains a table." End If If TextElement.supportsService("com.sun.star.text.Paragraph") Then MsgBox "The current block contains a paragraph." End If Wend
L'esempio crea un oggetto documento Doc che fa riferimento al documento di Apache OpenOffice attivo. Con l'ausilio di Doc, l'esempio crea un oggetto Enumeration che vaglia le singole parti del testo (paragrafi e tabelle) e assegna l'elemento attivo all'oggetto TextElement. In questo esempio viene usato il metodo supportsService per determinare se TextElement è un paragrafo o una tabella.
Paragrafi
Il servizio com.sun.star.text.Paragraph garantisce l'accesso al contenuto di un paragrafo. Il testo nel paragrafo può essere recuperato e modificato utilizzando la proprietà String:
Dim Doc As Object Dim Enum As Object Dim TextElement As Object Doc = StarDesktop.CurrentComponent Enum = Doc.Text.createEnumeration While Enum.hasMoreElements TextElement = Enum.nextElement If TextElement.supportsService("com.sun.star.text.Paragraph") Then TextElement.String = Replace(TextElement.String, "you", "U") TextElement.String = Replace(TextElement.String, "too", "2") TextElement.String = Replace(TextElement.String, "for", "4") End If Wend
L'esempio apre il documento di testo attivo e lo analizza con l'ausilio dell'oggetto Enumeration. Utilizza la proprietà TextElement.String in tutti i paragrafi per accedere ai paragrafi pertinenti e sostituisce le stringhe you, too and for con i caratteri U, 2 and 4. La funzione Replace utilizzata per la sostituzione non rientra nella portata standard del linguaggio Apache OpenOffice Basic. Questo caso illustra la funzione di esempio descritta in Ricerca e sostituzione.
Non esiste alcuna controparte in Apache OpenOffice Basic per gli elenchi Characters, Sentences e Words disponibili in VBA. Si ha tuttavia l'opzione di passare a TextCursor, che permette di spostarsi a livello di caratteri, frasi e parole.
Parti di paragrafi
L'esempio precedente può modificare il testo come richiesto, ma talvolta può anche distruggere la formattazione.
Ciò avviene poiché un paragrafo è a sua volta formato da singoli sub-oggetti. Ciascuno di questi sub-oggetti contiene le relative informazioni di formattazione. Se il centro di un paragrafo, ad esempio, contiene una parola in grassetto, sarà rappresentata in Apache OpenOffice da tre parti di paragrafo: la parte prima del grassetto, la parola in grassetto e infine la parte dopo il grassetto, che è nuovamente raffigurata come normale.
Se il testo del paragrafo viene ora modificato utilizzando la proprietà String del paragrafo, Apache OpenOffice elimina prima le vecchie parti del paragrafo e quindi inserisce una nuova parte del paragrafo. La formattazione delle sezioni precedenti va quindi persa.
Per evitare ciò, l'utente può accedere alle parti di paragrafo associate invece che all'intero paragrafo. I paragrafi forniscono un oggetto Enumeration a parte a tale fine. L'esempio seguente mostra un doppio ciclo che vaglia tutti i paragrafi di un documento di testo e le parti di paragrafi in essi contenute, quindi applica i processi di sostituzione dell'esempio precedente:
Dim Doc As Object Dim Enum1 As Object Dim Enum2 As Object Dim TextElement As Object Dim TextPortion As Object Doc = StarDesktop.CurrentComponent Enum1 = Doc.Text.createEnumeration ' loop over all paragraphs While Enum1.hasMoreElements TextElement = Enum1.nextElement If TextElement.supportsService("com.sun.star.text.Paragraph") Then Enum2 = TextElement.createEnumeration ' loop over all sub-paragraphs While Enum2.hasMoreElements TextPortion = Enum2.nextElement MsgBox "'" & TextPortion.String & "'" TextPortion.String = Replace(TextPortion.String, "you", "U") TextPortion.String = Replace(TextPortion.String, "too", "2") TextPortion.String = Replace(TextPortion.String, "for", "4") Wend End If Wend
L'esempio viene eseguito su un documento di testo in un doppio ciclo. Il ciclo esterno fa riferimento ai paragrafi del testo. Il ciclo interno elabora invece le parti di paragrafo in tali paragrafi. Il codice di esempio modifica il contenuto in ciascuna di tali parti di paragrafo utilizzando la proprietà String della stringa, come nell'esempio precedente per i paragrafi. Tuttavia, dato che le parti di paragrafo sono modificate direttamente, le relative informazioni di formattazione vengono conservate quando si sostituisce la stringa.
Formattazione
Esistono diversi modi per formattare un testo. Quello più semplice consiste nell'assegnare le proprietà di formattazione direttamente alla sequenza di testo ed è denominato formattazione diretta. La formattazione diretta è utilizzata soprattutto per i documenti brevi, poiché i formati possono essere assegnati dall'utente con il mouse. È possibile, ad esempio, evidenziare una determinata parola all'interno di un testo utilizzando lo stile grassetto oppure centrare una riga.
Oltre alla formattazione diretta, si possono formattare i testi anche utilizzando i modelli. Questa operazione è denominata formattazione indiretta. Con la formattazione indiretta, l'utente assegna un modello predefinito alla parte di testo pertinente. Se il layout del testo viene modificato in un secondo momento, l'utente deve pertanto modificare solo il modello. Apache OpenOffice modifica le modalità di raffigurazione di tutte le parti di testo che utilizzano tale modello.
Proprietà dei caratteri
Le proprietà di formattazione che si riferiscono a singoli caratteri sono descritte come proprietà dei caratteri e includono il grassetto e il tipo di carattere. Gli oggetti che consentono l'impostazione delle proprietà dei caratteri devono supportare il servizio com.sun.star.style.CharacterProperties. Apache OpenOffice riconosce un'ampia gamma di servizi che supportano il servizio, tra cui i servizi com.sun.star.text.Paragraph di cui sopra per i paragrafi nonché i servizi com.sun.star.text.TextPortion per le parti dei paragrafi.
Il servizio com.sun.star.style.CharacterProperties non fornisce interfacce, ma offre una serie di proprietà attraverso le quali è possibile definire e richiamare le proprietà dei caratteri. Un elenco completo di tutte le proprietà dei caratteri è reperibile nel riferimento dell'API di Apache OpenOffice. L'elenco seguente descrive le proprietà più importanti:
- CharFontName (String)
- Nome del tipo di carattere selezionato.
- CharColor (Long)
- Colore del testo.
- CharHeight (Float)
- Altezza del carattere in punti (pt).
- CharUnderline (Constant group)
- Tipo di trattino di sottolineatura (costanti conformi a com.sun.star.awt.FontUnderline).
- CharWeight (Constant group)
- Spessore del carattere (costanti conformi a com.sun.star.awt.FontWeight).
- CharBackColor (Long)
- Colore di sfondo.
- CharKeepTogether (Boolean)
- Soppressione del testo a capo automatico.
- CharStyleName (String)
- Nome del modello di carattere.
Proprietà dei paragrafi
Le informazioni di formattazione che non fanno riferimento a singoli caratteri bensì all'intero paragrafo sono considerate proprietà del paragrafo. Includono la distanza del paragrafo dal bordo della pagina nonché l'interlinea. Le proprietà dei paragrafi sono disponibili tramite il servizio com.sun.star.style.ParagraphProperties.
Anche le proprietà dei paragrafi sono disponibili in diversi oggetti. Tutti gli oggetti che supportano il servizio com.sun.star.text.Paragraph garantiscono anche il supporto delle proprietà dei paragrafi in com.sun.star.style.ParagraphProperties.
Un elenco completo di tutte le proprietà dei paragrafi è reperibile nel riferimento dell'API di Apache OpenOffice. Le proprietà dei paragrafi di uso più comune sono le seguenti:
- ParaAdjust (enum)
- Orientamento verticale del testo (costanti conformi a com.sun.star.style.ParagraphAdjust).
- ParaLineSpacing (struct)
- Interlinea (struttura conforme a com.sun.star.style.LineSpacing).
- ParaBackColor (Long)
- Colore di sfondo.
- ParaLeftMargin (Long)
- Margine sinistro in centesimi di millimetro.
- ParaRightMargin (Long)
- Margine destro in centesimi di millimetro.
- ParaTopMargin (Long)
- Margine superiore in centesimi di millimetro.
- ParaBottomMargin (Long)
- Margine inferiore in centesimi di millimetro.
- ParaTabStops (Array of struct)
- Tipo e posizione delle tabulazioni (matrice con strutture di Typs com.sun.star.style.TabStop).
- ParaStyleName (String)
- Nome del modello del paragrafo.
Esempio: esportazione in un file HTML semplice
L'esempio seguente mostra come utilizzare le informazioni di formattazione eseguendo un'iterazione nel documento di testo e creando un semplice file HTML. A tal fine, ogni paragrafo è registrato in un elemento HTML <P> a parte. Durante l'esportazione, le parti di paragrafo visualizzate in grassetto sono contrassegnate per mezzo dell'elemento HTML <B>.
Dim FileNo As Integer, Filename As String, CurLine As String Dim Doc As Object Dim Enum1 As Object, Enum2 As Object Dim TextElement As Object, TextPortion As Object Filename = "c:\text.html" FileNo = Freefile Open Filename For Output As #FileNo Print #FileNo, "<HTML><BODY>" Doc = StarDesktop.CurrentComponent Enum1 = Doc.Text.createEnumeration ' loop over all paragraphs While Enum1.hasMoreElements TextElement = Enum1.nextElement If TextElement.supportsService("com.sun.star.text.Paragraph") Then Enum2 = TextElement.createEnumeration CurLine = "<P>" ' loop over all paragraph portions While Enum2.hasMoreElements TextPortion = Enum2.nextElement If TextPortion.CharWeight = com.sun.star.awt.FontWeight.BOLD THEN CurLine = CurLine & "<B>" & TextPortion.String & "</B>" Else CurLine = CurLine & TextPortion.String End If Wend ' output the line CurLine = CurLine & "</P>" Print #FileNo, CurLine End If Wend ' write HTML footer Print #FileNo, "</BODY></HTML>" Close #FileNo
La struttura base dell'esempio è orientata agli esempi per l'esecuzione su parti di paragrafi di un testo già presentato in precedenza. Sono state aggiunte le funzioni per scrivere il file HTML, nonché un codice di prova che controlla lo spessore del carattere delle parti di testo corrispondenti e assegna alle parti del paragrafo in grassetto un tag HTML.
Valori predefiniti per le proprietà di caratteri e paragrafi
La formattazione diretta ha sempre la priorità rispetto alla formattazione indiretta. In altre parole, alla formattazione tramite modelli è assegnata un priorità inferiore rispetto alla formattazione diretta in un testo.
Determinare se una sezione di un documento è stata formattata in modo diretto o indiretto non è compito facile. Le barre dei simboli fornite da Apache OpenOffice mostrano le proprietà di testo comuni quali tipo di carattere, spessore e dimensioni. Tuttavia, non chiariscono se le impostazioni corrispondenti sono basate su modelli o sulla formattazione diretta del testo.
Apache OpenOffice Basic mette a disposizione il metodo getPropertyState, con il quale i programmatori possono controllare come è stata formattata una determinata proprietà. Come parametro, questo assume il nome della proprietà e restituisce una costante che fornisce informazioni sull'origine della formattazione. Sono possibili le risposte seguenti, definite nell'enumerazione di com.sun.star.beans.PropertyState:
- com.sun.star.beans.PropertyState.DIRECT_VALUE
- La proprietà è definita direttamente nel testo (formattazione diretta)
- com.sun.star.beans.PropertyState.DEFAULT_VALUE
- La proprietà è definita tramite un modello (formattazione indiretta)
- com.sun.star.beans.PropertyState.AMBIGUOUS_VALUE
- L'origine della proprietà non è chiara. Questo stato si presenta, ad esempio, quando si ricerca la proprietà grassetto di un paragrafo, che include sia le parole riportate in grassetto che quelle in caratteri normali.
L'esempio seguente mostra come modificare le proprietà di formattazione in Apache OpenOffice. Ricerca all'interno del testo le parti dei paragrafi che sono state rappresentate come grassetto utilizzando la formattazione diretta. Se individua una parte di paragrafo corrispondente, elimina la formattazione diretta utilizzando il metodo setPropertyToDefault e assegna un modello di carattere MyBold alla parte di paragrafo corrispondente.
Dim Doc As Object Dim Enum1 As Object Dim Enum2 As Object Dim TextElement As Object Dim TextPortion As Object Doc = StarDesktop.CurrentComponent Enum1 = Doc.Text.createEnumeration ' loop over all paragraphs While Enum1.hasMoreElements TextElement = Enum1.nextElement If TextElement.supportsService("com.sun.star.text.Paragraph") Then Enum2 = TextElement.createEnumeration ' loop over all paragraph portions While Enum2.hasMoreElements TextPortion = Enum2.nextElement If TextPortion.CharWeight = _ com.sun.star.awt.FontWeight.BOLD AND _ TextPortion.getPropertyState("CharWeight") = _ com.sun.star.beans.PropertyState.DIRECT_VALUE Then TextPortion.setPropertyToDefault("CharWeight") TextPortion.CharStyleName = "MyBold" End If Wend End If Wend
Content on this page is licensed under the Public Documentation License (PDL). |