Difference between revisions of "EN/Documentation/BASIC Guide/More Than Text"

Revision as of 18:21, 25 June 2009

Template:EN/Documentation/BASICGuideTOC/v2

Fino a questo punto, nel capitolo sono stati trattati solo paragrafi di testo e relative parti. Tuttavia i documenti di testo possono contenere anche altri oggetti, tra cui tabelle, disegni, campi di testo e directory. Tutti questi oggetti possono essere ancorati a qualsiasi punto all'interno del testo.

Grazie a queste caratteristiche comuni, tutti questi oggetti supportano in Apache OpenOffice un servizio di base comune denominato com.sun.star.text.TextContent, che fornisce le seguenti proprietà:

AnchorType (Enum)

Determina il tipo di ancoraggio di un oggetto TextContent (valori predefiniti conformi all'enumerazione com.sun.star.text.TextContentAnchorType).

AnchorTypes (sequence of Enum)

Enumerazione di tutti gli AnchorTypes che supportano un oggetto TextContent speciale.

TextWrap (Enum)

Determina il tipo di scorrimento del testo attorno a un oggetto TextContent (valori predefiniti conformi all'enumerazione com.sun.star.text.WrapTextMode).

Gli oggetti TextContent condividono anche alcuni metodi, in particolare quelli per creare, inserire ed eliminare gli oggetti.

• Per creare un nuovo oggetto TextContent' utilizzare il metodo createInstance dell'oggetto documento.
• Per inserire un nuovo oggetto ' utilizzare il metodo insertTextContent dell'oggetto di testo.
• Per eliminare un oggetto

                   TextContent' utilizzare il metodo removeTextContent.

Nelle sezioni seguenti viene presentata una serie di esempi che si avvalgono di questi metodi.

Tabelle

L'esempio seguente crea una tabella con l'ausilio del metodo createInstance descritto in precedenza.

Dim Doc As Object
Dim Table As Object
Dim Cursor As Object
 
Doc = StarDesktop.CurrentComponent
Cursor = Doc.Text.createTextCursor()
 
Table = Doc.createInstance("com.sun.star.text.TextTable")
Table.initialize(5, 4)
 
Doc.Text.insertTextContent(Cursor, Table, False)

Esempi Python:

def inset_img(): 
   # abstract the objects in varialbes, doc, text and img, note we used the XSCRIPTCONTEXT
   doc = XSCRIPTCONTEXT.getDocument() 
   text = doc.getText() 
   cursor = text.createTextCursor()  # not sure
   Table = doc.createInstance(u'com.sun.star.text.TextTable') 
 
   # Verify code
   Table.initialize(5, 4)
 
   #inser the image in the text area location    
   text.insertTextContent(text.getEnd(), Table, False)

Una volta creata, la tabella viene impostata sul numero di righe e colonne richieste utilizzando una chiamata initialize e quindi inserita nel documento di testo con insertTextContent.

                   .

Come illustrato nell'esempio, il metodo insertTextContent prevede non solo l'inserimento dell'oggetto Content, ma anche l'inserimento di altri due parametri:

• un oggetto Cursor che determina la posizione di inserimento
• una variabile booleana che specifica se l'oggetto Content deve sostituire la selezione corrente del cursore (valore True) o se deve essere inserito nel testo prima della selezione corrente (valore False).

Template:Documentation/Note

È possibile determinare le tabelle inserite in un documento di testo utilizzando un semplice ciclo. A tal fine è utilizzato il metodo getTextTables() dell'oggetto documento di testo:

Dim Doc As Object
Dim TextTables As Object
Dim Table As Object
Dim I As Integer
Doc = StarDesktop.CurrentComponent
TextTables = Doc.getTextTables()
For I = 0 to TextTables.count - 1
 
   Table = TextTables(I)
   ' Editing table
 
Next I

Template:Documentation/Note

Modifica delle tabelle

Una tabella è formata da singole righe che a loro volta contengono diverse celle. In senso stretto, in Apache OpenOffice non sono presenti colonne di tabelle, che vengono prodotte in modo implicito disponendo le righe (una sotto l'altra) una accanto all'altra. Per semplificare l'accesso alle tabelle, Apache OpenOffice fornisce tuttavia alcuni metodi che operano utilizzando le colonne e risultano di particolare utilità se nella tabella non si è eseguita l'unione di più celle.

Ma è opportuno osservare prima le proprietà della tabella stessa. Esse sono definite nel servizio com.sun.star.text.TextTable. Di seguito viene riportato un elenco delle più importanti proprietà dell'oggetto tabella:

BackColor (Long)

Colore di sfondo della tabella.

BottomMargin (Long)

Margine inferiore in centesimi di millimetro.

LeftMargin (Long)

Margine sinistro in centesimi di millimetro.

RightMargin (Long)

Margine destro in centesimi di millimetro.

TopMargin (Long)

Margine superiore in centesimi di millimetro.

RepeatHeadline (Boolean)

L'intestazione della tabella viene ripetuta su ogni pagina.

Width (Long)

Larghezza assoluta della tabella in centesimi di millimetro.

Righe

Una tabella è formata da un elenco contenente una serie di righe. L'esempio seguente mostra come richiamare e formattare le righe di una tabella.

Dim Doc As Object
Dim Table As Object
Dim Cursor As Object
Dim Rows As Object
Dim Row As Object
Dim I As Integer
 
Doc = StarDesktop.CurrentComponent
Cursor = Doc.Text.createTextCursor()
 
Table = Doc.createInstance("com.sun.star.text.TextTable")
Table.initialize(5, 4)
 
Doc.Text.insertTextContent(Cursor, Table, False)
Rows = Table.getRows
For I = 0 To Rows.getCount() - 1
   Row = Rows.getByIndex(I)
   Row.BackColor = &HFF00FF
Next

In primo luogo l'esempio crea un elenco contenente tutte le righe utilizzando una chiamata Table.getRows. I metodi getCount e getByIndex consentono l'ulteriore elaborazione dell'elenco e appartengono all'interfaccia com.sun.star.table.XtableRows. Il metodo getByIndex restituisce un oggetto riga, che supporta il servizio com.sun.star.text.TextTableRow.

Di seguito vengono riportati i metodi principali dell'interfaccia com.sun.star.table.XtableRows:

getByIndex(Integer)

Restituisce un oggetto riga per l'indice specificato.

getCount()

Restituisce il numero di oggetti riga.

insertByIndex(Index, Count)

Inserisce un numero di righe pari a Count nella tabella alla posizione di Index.

removeByIndex(Index, Count)

Elimina un numero di righe pari a Count dalla tabella alla posizione di Index.

Mentre i metodi getByIndex e getCount sono disponibili in tutte le tabelle, i metodi insertByIndex e removeByIndex si possono utilizzare solo nelle tabelle che non contengono celle precedentemente unite.

Il servizio com.sun.star.text.TextTableRow fornisce le proprietà seguenti:

BackColor (Long)

Colore di sfondo della riga.

Height (Long)

Altezza della riga in centesimi di millimetro.

IsAutoHeight (Boolean)

L'altezza della tabella viene adattata dinamicamente al suo

contenuto.

VertOrient (const)

Orientamento verticale della cornice di testo – dettagli sull'orientamento verticale del testo all'interno della tabella (valori conformi a com.sun.star.text.VertOrientation)

Colonne

Per accedere alle colonne si procede come con le righe, utilizzando i metodi getByIndex, getCount, insertByIndex e removeByIndex sull'oggetto Column raggiungibile tramite getColumns. Li potrete però utilizzare solo nelle tabelle che non contengono celle precedentemente unite. In Apache OpenOffice Basic le celle non possono essere formattate per colonna. Per procedere comunque in tal senso, dovete avvalervi del metodo di formattazione delle singole celle della tabella.

Celle

Ogni cella di un documento di Apache OpenOffice ha un nome univoco. Se il cursore di Apache OpenOffice si trova in una cella, il nome della cella viene visualizzato nella barra di stato. La cella superiore sinistra è generalmente denominata A1, mentre quella inferiore destra è denominata Xn, dove X rappresenta le lettere della colonna superiore e n i numeri dell'ultima riga. Gli oggetti cella sono disponibili tramite il metodo getCellByName() dell'oggetto tabella. L'esempio seguente mostra un ciclo che vaglia tutte le celle di una tabella e inserisce i numeri di riga e colonna corrispondenti nelle celle.

Dim Doc As Object
Dim Table As Object
Dim Cursor As Object
Dim Rows As Object
Dim RowIndex As Integer
Dim Cols As Object
Dim ColIndex As Integer
Dim CellName As String
Dim Cell As Object
 
Doc = StarDesktop.CurrentComponent
Cursor = Doc.Text.createTextCursor()
 
Table = Doc.createInstance("com.sun.star.text.TextTable")
Table.initialize(5, 4)
 
Doc.Text.insertTextContent(Cursor, Table, False)
 
Rows = Table.getRows
Cols = Table.getColumns
 
For RowIndex = 1 To Rows.getCount()
   For ColIndex = 1 To Cols.getCount()
      CellName = Chr(64 + ColIndex) & RowIndex
      Cell = Table.getCellByName(CellName)
      Cell.String = "row: " & CStr(RowIndex) + ", column: " & CStr(ColIndex)
   Next
Next

La cella di una tabella è paragonabile a un testo standard e supporta l'interfaccia createTextCursor per creare un oggetto TextCursor associato.

CellCursor = Cell.createTextCursor()

Tutte le opzioni di formattazione per i singoli caratteri e paragrafi sono quindi automaticamente disponibili.

L'esempio seguente esegue una ricerca in tutte le tabelle di un documento di testo e applica il formato allineato a destra a tutte le celle con valori numerici per mezzo della proprietà di paragrafo corrispondente.

Dim Doc As Object
Dim TextTables As Object
Dim Table As Object
Dim CellNames
Dim Cell As Object
Dim CellCursor As Object
Dim I As Integer
Dim J As Integer
 
Doc = StarDesktop.CurrentComponent
TextTables = Doc.getTextTables()
 
For I = 0 to TextTables.count - 1
   Table = TextTables(I)
   CellNames = Table.getCellNames()
 
   For J = 0 to UBound(CellNames)
      Cell = Table.getCellByName(CellNames(J))
      If IsNumeric(Cell.String) Then
         CellCursor = Cell.createTextCursor()
         CellCursor.paraAdjust = com.sun.star.style.ParagraphAdjust.RIGHT
      End If
   Next
Next

L'esempio crea un elenco TextTables contenente tutte le tabelle di un testo attraversate nel ciclo. Apache OpenOffice crea quindi un elenco dei nomi delle celle associate per ognuna di queste tabelle, che vengono vagliate a turno nel ciclo. Se una cella contiene un valore numerico, l'esempio modifica la formattazione di conseguenza. Per procedere in tal senso, crea prima un oggetto TextCursor che fa riferimento al contenuto della cella della tabella, quindi adatta le proprietà del paragrafo alla cella.

Cornici di testo

Le cornici di testo sono considerate oggetti TextContent, proprio come le tabelle e i grafici e possono essere costituite essenzialmente da testo standard, sebbene siano collocabili in qualsiasi posizione della pagina e non vengano incluse nel flusso del testo.

Come con tutti gli oggetti TextContent, anche nelle cornici di testo si opera una distinzione tra creazione effettiva e inserimento nel documento.

Dim Doc As Object
Dim TextTables As Object
Dim Cursor As Object
Dim Frame As Object
 
Doc = StarDesktop.CurrentComponent
Cursor = Doc.Text.createTextCursor()
Frame = Doc.createInstance("com.sun.star.text.TextFrame")
Doc.Text.insertTextContent(Cursor, Frame, False)

Per creare la cornice di testo, utilizzate il metodo createInstance dell'oggetto documento. La cornice di testo così creata può essere poi inserita nel documento utilizzando il metodo insertTextContent dell'oggetto Text. In questa operazione dovrete specificare il nome del servizio com.sun.star.text.TextFrame corretto.

La posizione di inserimento della cornice di testo è determinata da un oggetto Cursor che viene inoltre eseguito all'inserimento.

Template:Documentation/Note

Gli oggetti cornice di testo forniscono una serie di proprietà con le quali influenzare la posizione e il funzionamento della cornice. La maggior parte di tali proprietà è definita nel servizio com.sun.star.text.BaseFrameProperties, che è supportato anche da ogni servizio TextFrame. Le proprietà principali sono le seguenti:

BackColor (Long)

Colore di sfondo della cornice di testo.

BottomMargin (Long)

Margine inferiore in centesimi di millimetro.

LeftMargin (Long)

Margine sinistro in centesimi di millimetro.

RightMargin (Long)

Margine destro in centesimi di millimetro.

TopMargin (Long)

Margine superiore in centesimi di millimetro.

Height (Long)

Altezza della cornice di testo in centesimi di millimetro.

Width (Long)

Larghezza della cornice di testo in centesimi di millimetro.

HoriOrient (const)

Orientamento orizzontale della cornice di testo (conforme a com.sun.star.text.HoriOrientation).

VertOrient (const)

Orientamento verticale della cornice di testo (conforme a com.sun.star.text.VertOrientation).

L'esempio seguente crea una cornice di testo utilizzando le proprietà descritte in precedenza:

Dim Doc As Object
Dim TextTables As Object
Dim Cursor As Object
Dim Frame As Object
 
Doc = StarDesktop.CurrentComponent
Cursor = Doc.Text.createTextCursor()
Cursor.gotoNextWord(False)
Frame = Doc.createInstance("com.sun.star.text.TextFrame")
 
Frame.Width = 3000
Frame.Height = 1000
Frame.AnchorType = com.sun.star.text.TextContentAnchorType.AS_CHARACTER
Frame.TopMargin = 0
Frame.BottomMargin = 0
Frame.LeftMargin = 0
Frame.RightMargin = 0
Frame.BorderDistance = 0
Frame.HoriOrient = com.sun.star.text.HoriOrientation.NONE
Frame.VertOrient = com.sun.star.text.VertOrientation.LINE_TOP
 
Doc.Text.insertTextContent(Cursor, Frame, False)

L'esempio crea un TextCursor come segno di inserimento per la cornice di testo, posizionato tra la prima e la seconda parola del testo. La cornice di testo viene creata utilizzando Doc.createInstance. Le proprietà degli oggetti cornice di testo sono impostate sui valori iniziali richiesti.

Osservate l'interazione tra le proprietà AnchorType (dal servizio TextContent) e VertOrient (dal servizio BaseFrameProperties). AnchorType riceve il valore AS_CHARACTER. La cornice viene pertanto inserita direttamente nel flusso del testo e funziona come un carattere. Può, ad esempio, essere spostata nella riga successiva se si verifica un a capo. Il valore LINE_TOP della proprietà VertOrient garantisce che il bordo superiore della cornice di testo sia alla stessa altezza del bordo superiore del carattere.

Una volta completata l'inizializzazione, la cornice di testo viene infine inserita nel documento di testo utilizzando una chiamata da insertTextContent.

Per modificare il contenuto di una cornice di testo, l'utente si avvale del TextCursor, già citato varie volte e disponibile anche per le cornici di testo.

Dim Doc As Object
Dim TextTables As Object
Dim Cursor As Object
Dim Frame As Object
Dim FrameCursor As Object
 
Doc = StarDesktop.CurrentComponent
Cursor = Doc.Text.createTextCursor()
Frame = Doc.createInstance("com.sun.star.text.TextFrame")
 
Frame.Width = 3000
Frame.Height = 1000
 
Doc.Text.insertTextContent(Cursor, Frame, False)
 
FrameCursor = Frame.createTextCursor()
FrameCursor.charWeight = com.sun.star.awt.FontWeight.BOLD
FrameCursor.paraAdjust = com.sun.star.style.ParagraphAdjust.CENTER
FrameCursor.String = "This is a small Test!"

L'esempio crea una cornice di testo, la inserisce nel documento corrente e apre un TextCursor per la cornice di testo. Questo cursore viene impiegato per impostare il carattere della cornice su grassetto e l'orientamento del paragrafo su centrato. Infine alla cornice di testo viene assegnata la stringa "This is a small test!" .

Campi di testo

I campi di testo sono oggetti TextContent, in quanto forniscono funzionalità addizionali che vanno oltre il semplice testo. Possono essere inseriti in un documento di testo utilizzando gli stessi metodi impiegati per gli altri oggetti TextContent:

Dim Doc As Object
Dim DateTimeField As Object
Dim Cursor As Object
Doc = StarDesktop.CurrentComponent
Cursor = Doc.Text.createTextCursor()
 
DateTimeField = Doc.createInstance("com.sun.star.text.TextField.DateTime")
DateTimeField.IsFixed = False
DateTimeField.IsDate = True
Doc.Text.insertTextContent(Cursor, DateTimeField, False)

L'esempio inserisce un campo di testo con la data corrente all'inizio del documento di testo corrente. Il valore True della proprietà IsDate produce la visualizzazione della sola data e non dell'ora. Il valore False per IsFixed garantisce che la data venga automaticamente aggiornata all'apertura del documento.

Template:Documentation/Note

In passato, si accedeva ai campi di testo utilizzando una serie completa di metodi resi disponibili da Apache OpenOffice nell'oggetto obsoleto Selection (ad esempio InsertField, DeleteUserField, SetCurField)).

In Apache OpenOffice 2.x, i campi vengono invece gestiti utilizzando un concetto orientato agli oggetti. Per creare un campo di testo, dovete prima creare un campo di testo del tipo richiesto e quindi inizializzarlo utilizzando le proprietà necessarie. Il campo di testo viene poi inserito nel documento con il metodo insertTextContent. Nell'esempio precedente è illustrato un testo sorgente corrispondente. I tipi di campi più importanti e le relative proprietà sono descritti nelle sezioni che seguono.

Oltre all'inserimento dei campi di testo, anche la ricerca dei campi in un documento può costituire un'attività importante. L'esempio seguente mostra come vagliare in un ciclo tutti i campi di testo di un documento di testo e controllarne il tipo di pertinenza.

Dim Doc As Object
Dim TextFieldEnum As Object
Dim TextField As Object
Dim I As Integer
 
Doc = StarDesktop.CurrentComponent
 
TextFieldEnum = Doc.getTextFields.createEnumeration
 
While TextFieldEnum.hasMoreElements()
 
   TextField = TextFieldEnum.nextElement()
 
   If TextField.supportsService("com.sun.star.text.TextField.DateTime") Then
      MsgBox "Date/time"
   ElseIf TextField.supportsService("com.sun.star.text.TextField.Annotation") Then
      MsgBox "Annotation"
   Else
      MsgBox "unknown"
   End If
 
Wend

Il punto iniziale per determinare i campi di testo presenti è l'elenco TextFields dell'oggetto documento. L'esempio crea un oggetto Enumeration sulla base di questo elenco, con il quale è possibile vagliare uno per volta tutti i campi di testo in un ciclo. I campi di testo individuati vengono controllati per verificare il servizio supportato utilizzando il metodo supportsService. Se il campo risulta essere del tipo per data/ora o annotazioni, il tipo di campo corrispondente viene visualizzato in una casella di informazioni. Se per contro l'esempio incontra un altro campo, visualizza l'informazione "sconosciuto".

Di seguito viene riportato un elenco dei campi di testo più importanti e delle relative proprietà associate. Un elenco completo di tutti i campi di testo è fornito nel riferimento dell'API nel modulo com.sun.star.text.TextField. (Per l'elencazione dei nomi di servizi di un campo di testo, utilizzate in Apache OpenOffice Basic caratteri in maiuscolo e in minuscolo, come nell'esempio precedente).

Numeri di pagine, parole e caratteri

I campi di testo

• com.sun.star.text.TextField.PageCount
• com.sun.star.text.TextField.WordCount
• com.sun.star.text.TextField.CharacterCount

restituiscono il numero di pagine, parole e caratteri di un testo e supportano la proprietà seguente:

NumberingType (const)

formato di numerazione (regole conformi alle costanti di com.sun.star.style.NumberingType).

Pagina corrente

Il numero della pagina corrente può essere inserito nel documento utilizzando il campo di testo com.sun.star.text.TextField.PageNumber. È possibile specificare le proprietà seguenti:

NumberingType (const)

Formato numerico (regole conformi alle costanti di com.sun.star.style.NumberingType).

Offset (short)

Correzione aggiunta al numero di pagine (è possibile anche la specifica negativa).

L'esempio seguente mostra come inserire il numero di pagine nel piè di pagina di un documento.

Dim Doc As Object
Dim DateTimeField As Object
Dim PageStyles As Object
Dim StdPage As Object
Dim FooterCursor As Object
Dim PageNumber As Object
 
Doc = StarDesktop.CurrentComponent
 
PageNumber = Doc.createInstance("com.sun.star.text.TextField.PageNumber")
PageNumber.NumberingType = com.sun.star.style.NumberingType.ARABIC
 
PageStyles = Doc.StyleFamilies.getByName("PageStyles")
 
StdPage = PageStyles("Default")
StdPage.FooterIsOn = True
 
FooterCursor = StdPage.FooterTextLeft.Text.createTextCursor()
StdPage.FooterTextLeft.Text.insertTextContent(FooterCursor, PageNumber, False)

L'esempio crea prima un campo di testo che supporta il servizio com.sun.star.text.TextField.PageNumber. Poiché le righe di intestazione e piè di pagina sono definite come parte dei modelli di pagina di Apache OpenOffice, la determinazione iniziale viene effettuata utilizzando l'elenco di tutti i PageStyles.

Per garantire che la riga del piè di pagina sia visibile, la proprietà FooterIsOn è impostata su True. Il campo di testo viene quindi inserito nel documento utilizzando l'oggetto testo associato della riga del piè di pagina di sinistra.

Annotazioni

I campi di annotazioni (com.sun.star.text.TextField.Annotation) vengono visualizzati per mezzo di un simbolino giallo nel testo. Facendo clic su questo simbolo si apre un campo di testo, in cui potrete registrare un commento sul punto corrente nel testo. Un campo di annotazione possiede le seguenti proprietà:

Author (String)

nome dell'autore.

Content (String)

testo di commento.

Date (Date)

data in cui è scritta l'annotazione.

Data/ora

Un campo data/ora (com.sun.star.text.TextField.DateTime) rappresenta la data o l'ora correnti e supporta le proprietà seguenti:

IsFixed (Boolean)

Se è True, i dettagli dell'ora di inserimento rimangono invariati; se è False, vengono aggiornati a ogni apertura del documento.

IsDate (Boolean)

Se è True, il campo visualizza la data corrente, altrimenti l'ora

corrente.

DateTimeValue (struct)

Contenuto corrente del campo (struttura com.sun.star.util.DateTime)

NumberFormat (const)

Formato di visualizzazione dell'ora o della data.

Nome/numero del capitolo

Il nome del capitolo corrente è disponibile tramite un campo di testo del tipo com.sun.star.text.TextField.Chapter. La modalità può essere definita mediante due proprietà.

ChapterFormat (const)

Determina se è riportato il nome o il numero del capitolo (conformemente a com.sun.star.text.ChapterFormat)

Level (Integer)

Determina il livello del capitolo per il quale visualizzare nome e/o numero. Il valore 0 rappresenta il livello più alto disponibile.

Segnalibri

I segnalibri (servizio com.sun.star.text.Bookmark) sono oggetti TextContent. I segnalibri vengono creati e inseriti utilizzando il concetto seguente, già descritto in precedenza:

Dim Doc As Object
Dim Bookmark As Object
Dim Cursor As Object
 
Doc = StarDesktop.CurrentComponent
 
Cursor = Doc.Text.createTextCursor()
 
Bookmark = Doc.createInstance("com.sun.star.text.Bookmark")
Bookmark.Name = "My bookmarks"
Doc.Text.insertTextContent(Cursor, Bookmark, True)

L'esempio crea un Cursor, che contrassegna la posizione di inserimento del segnalibro e quindi l'effettivo oggetto segnalibro (Bookmark). Al segnalibro viene quindi assegnato un nome ed è inserito nel documento tramite insertTextContent, in corrispondenza della posizione del cursore.

È possibile accedere ai segnalibri di un testo tramite l'elenco denominato Bookmarks. Inoltre, potete accedere ai segnalibri per numero o per nome.

L'esempio seguente mostra come individuare un segnalibro all'interno del testo e inserire un testo nella posizione corrispondente.

Dim Doc As Object
Dim Bookmark As Object
Dim Cursor As Object
 
Doc = StarDesktop.CurrentComponent
 
Bookmark = Doc.Bookmarks.getByName("My bookmarks")
 
Cursor = Doc.Text.createTextCursorByRange(Bookmark.Anchor)
Cursor.String = "Here is the bookmark"

In questo esempio il metodo getByName è utilizzato per reperire il segnalibro richiesto tramite il nome. La chiamata createTextCursorByRange crea quindi un Cursor, che viene posizionato nella posizione di ancoraggio del segnalibro. Il cursore inserisce il testo richiesto in questo punto.