Difference between revisions of "EN/Documentation/BASIC Guide/Cells and Ranges"

Latest revision as of 14:44, 6 July 2018

Template:EN/Documentation/BASICGuideTOC/v2

Un foglio elettronico è costituito da un elenco bidimensionale contenente le celle. Ogni cella è definita dalla sua posizione X e Y rispetto alla cella superiore sinistra che ha la posizione (0,0).

Nell'esempio seguente viene creato un oggetto che fa riferimento alla cella superiore sinistra e viene inserito un testo nella cella:

Dim Doc As Object
Dim Sheet As Object
Dim Cell As Object   
 
Doc = StarDesktop.CurrentComponent
Sheet = Doc.Sheets(0)
 
Cell = Sheet.getCellByPosition(0, 0)
Cell.String = "Test"

StarDesktop.CurrentComponent restituisce il componente corrente. Se si lavora in BASIC IDE quando si esegue la macro, viene restituito il BASIC IDE. Viene generato un errore di RunTime poiché per BASIC IDE non è presente un componente di foglio elettronico. Salvare il codice di esempio ed eseguire la macro da un foglio elettronico. Per ulteriori informazioni vedere StarDesktop.

Oltre alle coordinate numeriche, a ogni cella di un foglio è assegnato un nome, ad esempio, la cella superiore sinistra (0,0) di un foglio elettronico è denominata A1. La lettera A rappresenta la colonna e il numero 1 la riga. È importante che il nome e la posizionedi una cella non vengano confusi perché il conteggio delle righe per nomi inizia con 1 ma il conteggio per posizione inizia con 0.

In Apache OpenOffice, una cella di tabella può essere vuota o contenere testo, numeri o formule. Il tipo di cella non è determinato dal contenuto salvato nella cella, bensì dalla proprietà dell'oggetto utilizzata per la sua immissione. I numeri possono essere inseriti e richiamati con la proprietà Value, il testo con la proprietà String

e le formule con la proprietà Formula.

Dim Doc As Object
Dim Sheet As Object
Dim Cell As Object   
 
Doc = StarDesktop.CurrentComponent
Sheet = Doc.Sheets(0)
 
Cell = Sheet.getCellByPosition(0, 0)
Cell.Value = 100
 
Cell = Sheet.getCellByPosition(0, 1)
Cell.String = "Test"
 
Cell = Sheet.getCellByPosition(0, 2)
Cell.Formula = "=A1"

L'esempio inserisce un numero, un testo e una formula nei campi da A1 a A3.

Le proprietà Value, String e Formula sostituiscono il metodo PutCell per l'impostazione dei valori di una cella di tabella.

Apache OpenOffice tratta come testo il contenuto delle celle inserito utilizzando la proprietà String, anche se il contenuto è un numero. I numeri inseriti sono allineati a sinistra all'interno della cella anziché a destra. Osservare inoltre la differenza tra testo e numeri quando si utilizzano le formule:

Dim Doc As Object
Dim Sheet As Object
Dim Cell As Object
 
Doc = StarDesktop.CurrentComponent
Sheet = Doc.Sheets(0)
 
Cell = Sheet.getCellByPosition(0, 0)
Cell.Value = 100
 
Cell = Sheet.getCellByPosition(0, 1)
Cell.String = 1000
 
Cell = Sheet.getCellByPosition(0, 2)
Cell.Formula = "=A1+A2"
 
MsgBox Cell.Value

Sebbene la cella A1 contenga il valore 100 e la cella A2 il valore 1000, la formula A1+A2 restituisce il valore 100, in quanto i contenuti della cella A2 erano stati immessi come stringa e non come numero.

Per controllare se i contenuti di una cella contengono un numero o una stringa, utilizzate la proprietà Type:

Dim Doc As Object
Dim Sheet As Object
Dim Cell As Object
 
Doc = StarDesktop.CurrentComponent
Sheet = Doc.Sheets(0)
Cell = Sheet.getCellByPosition(1,1)
 
Cell.Value = 1000
 
Select Case Cell.Type 
Case com.sun.star.table.CellContentType.EMPTY 
   MsgBox "Content: Empty"
Case com.sun.star.table.CellContentType.VALUE
   MsgBox "Content: Value"
Case com.sun.star.table.CellContentType.TEXT
   MsgBox "Content: Text"
Case com.sun.star.table.CellContentType.FORMULA
   MsgBox "Content: Formula"
End Select

La proprietà Cell.Type restituisce un valore per l'enumerazione com.sun.star.table.CellContentType che identifica il tipo di contenuti di una cella. Sono ammessi i seguenti valori:

EMPTY

Nessun valore

VALUE

Numero

TEXT

Stringhe

FORMULA

Formula

Inserimento, eliminazione, copia e spostamento delle celle

Oltre a modificare direttamente il contenuto delle celle, Apache OpenOffice Calc fornisce anche un'interfaccia che permette di inserire, eliminare, copiare o unire le celle. L'interfaccia (com.sun.star.sheet.XRangeMovement) è disponibile tramite l'oggetto foglio elettronico e fornisce quattro metodi per modificare il contenuto delle celle.

Il metodo insertCell è utilizzato per inserire le celle in un foglio.

Dim Doc As Object
Dim Sheet As Object
Dim CellRangeAddress As New com.sun.star.table.CellRangeAddress
 
Doc = StarDesktop.CurrentComponent
Sheet = Doc.Sheets(0)
 
CellRangeAddress.Sheet = 0
CellRangeAddress.StartColumn = 1
CellRangeAddress.StartRow = 1
CellRangeAddress.EndColumn = 2
CellRangeAddress.EndRow = 2
 
Sheet.insertCells(CellRangeAddress, com.sun.star.sheet.CellInsertMode.DOWN)

Questo esempio inserisce un intervallo di celle di dimensioni pari a due righe per due colonne nella seconda colonna e riga (ciascuna reca il numero 1) del primo foglio (numero 0) nel foglio elettronico. I valori già esistenti nell'intervallo di celle specificato vengono quindi spostati al di sotto di esso.

Per definire l'intervallo di celle da inserire, utilizzate la struttura com.sun.star.table.CellRangeAddress. I valori seguenti sono inclusi in questa struttura:

Sheet (short)

Numero del foglio (la numerazione inizia da 0).

StartColumn (long)

La prima colonna nell'intervallo di celle (la numerazione inizia da 0).

StartRow (long)

La prima riga nell'intervallo di celle (la numerazione inizia da 0).

EndColumn (long)

La colonna finale nell'intervallo di celle (la numerazione inizia da 0).

EndRow (long)

La riga finale nell'intervallo di celle (la numerazione inizia da 0).

La struttura CellRangeAddress completata deve essere trasmessa come primo parametro al metodo insertCells. Il secondo parametro di insertCells contiene un valore dell'enumerazione com.sun.star.sheet.CellInsertMode e definisce cosa fare con i valori situati davanti al punto di inserimento. L'enumerazione CellInsertMode riconosce i valori seguenti:

NONE

I valori correnti rimangono nella loro attuale posizione.

DOWN

Le celle in corrispondenza della posizione di inserimento e sotto di esso

sono spostate verso il basso.

RIGHT

Le celle in corrispondenza della posizione di inserimento e alla sua destra vengono spostate verso destra.

ROWS

Le righe dopo la posizione di inserimento vengono spostate verso il basso.

COLUMNS

Le colonne dopo la posizione di inserimento vengono spostate verso destra.

Il metodo removeRange è la controparte del metodo insertCells. Elimina l'intervallo definito nella struttura CellRangeAddress dalla tabella.

Dim Doc As Object
Dim Sheet As Object
Dim CellRangeAddress As New com.sun.star.table.CellRangeAddress
 
Doc = StarDesktop.CurrentComponent
Sheet = Doc.Sheets(0)
 
CellRangeAddress.Sheet = 0
CellRangeAddress.StartColumn = 1
CellRangeAddress.StartRow = 1
CellRangeAddress.EndColumn = 2
CellRangeAddress.EndRow = 2
 
Sheet.removeRange(CellRangeAddress, com.sun.star.sheet.CellDeleteMode.UP)

Questo esempio rimuove l'intervallo di celle B2:C3 dalla tabella, quindi sposta verso l'alto le celle sottostanti di due righe. Il tipo di rimozione è definito da uno dei valori seguenti dall'enumerazione com.sun.star.sheet.CellDeleteMode:

NONE

I valori correnti rimangono nella attuale posizione.

UP

Le celle in corrispondenza della posizione di inserimento vengono spostate verso l'alto.

LEFT

Le celle in corrispondenza della posizione di inserimento e alla sua destra

vengono spostate verso sinistra.

ROWS

Le righe dopo la posizione di inserimento vengono spostate verso l'alto.

COLUMNS

le colonne dopo la posizione di inserimento vengono spostate verso sinistra.

L'interfaccia XRangeMovement offre due ulteriori metodi per spostare (moveRange) o copiare (copyRange) gli intervalli di celle. L'esempio seguente sposta l'intervallo B2:C3 in modo da farlo iniziare alla posizione A6:

Dim Doc As Object
Dim Sheet As Object
Dim CellRangeAddress As New com.sun.star.table.CellRangeAddress
Dim CellAddress As New com.sun.star.table.CellAddress
 
Doc = StarDesktop.CurrentComponent
Sheet = Doc.Sheets(0)
 
CellRangeAddress.Sheet = 0
CellRangeAddress.StartColumn = 1
CellRangeAddress.StartRow = 1
CellRangeAddress.EndColumn = 2
CellRangeAddress.EndRow = 2
 
CellAddress.Sheet = 0
CellAddress.Column = 0
CellAddress.Row = 5
 
Sheet.moveRange(CellAddress, CellRangeAddress)

Oltre alla struttura CellRangeAdress, il metodo moveRange prevede una struttura com.sun.star.table.CellAddressper definire l'origine della regione di destinazione dello spostamento. Il metodo CellAddress fornisce i seguenti valori:

Sheet (short)

Numero del foglio elettronico (la numerazione inizia da 0).

Column (long)

Numero della colonna identificata (la numerazione inizia da 0).

Row (long)

Numero della riga identificata (la numerazione inizia da 0).

I contenuti della cella nell'intervallo di destinazione vengono sempre sovrascritti dal metodo moveRange. A differenza del metodo InsertCells, nel metodo removeRange non è fornito un parametro per l'esecuzione degli spostamenti automatici.

Il metodo copyRange</tt> funziona allo stesso modo del metodo <tt>moveRange, eccetto che copyRange inserisce una copia dell'intervallo di celle invece di spostarle.

In termini di funzionalità, i metodi Apache OpenOffice Basic insertCell, removeRange e copyRange sono paragonabili ai metodi Range.Insert, Range.Delete e Range.Copy di VBA. In VBA, però, i metodi sono applicati all'oggetto Range corrispondente, mentre in Apache OpenOffice Basic sono applicati all'oggetto Sheet associato.