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

Revision as of 18:22, 25 June 2009

Template:EN/Documentation/BASICGuideTOC/v2

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.

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.

Template:Documentation/Note

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.

Template:Documentation/Note

Template:Documentation/Note

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