Contenuto
Indice 🔎︎

# Servizio SFDocuments.Calc

La libreria SFDocuments fornisce una serie di metodi e proprietà che facilitano la gestione e la manipolazione di documenti di LibreOffice Calc.

Alcuni metodi sono generici per tutti i tipi di documenti e sono ereditati dal servizio Document, altri metodi invece sono specifici per il modulo SF_Calc.

Il SF_Calc è mirato per:

- Manipolare i fogli all'interno di un documento di Calc (copiare, inserire, spostare, ecc.)

- Scambiare dati tra strutture di dati in Basic e aree di Calc

- Copiare e importare grandi quantità di dati

## Invocare il servizio

Il servizio Calc è strettamente collegato al servizio UI della libreria ScriptForge. Di seguito sono riportati alcuni esempi di come il servizio Calc può essere invocato.

##### In Basic

Il frammento di codice sottostante crea l'istanza a un servizio Calc che corrisponde al documento di Calc attualmente attivo.

        Set oDoc = CreateScriptService("Calc")

Un altro modo di creare un'istanza del servizio Calc è quello di usare il servizio UI. Nell'esempio seguente viene creato un nuovo documento di Calc e oDoc è un'istanza del servizio Calc:

        Dim ui As Object, oDoc As Object
        Set ui = CreateScriptService("UI")
        Set oDoc = ui.CreateDocument("Calc")

Oppure usando il metodo OpenDocument del servizio UI:

        Set oDoc = ui.OpenDocument("C:\Documents\MyFile.ods")

È anche possibile istanziare il servizio Calc usando il metodo CreateScriptService:

        Dim oDoc As Object
        Set oDoc = CreateScriptService("SFDocuments.Calc", "MyFile.ods")

Nell'esempio sopra riportato, "MyFile.ods" è il nome di una finestra di apertura di un documento. Se l'argomento non è fornito, viene considerata la finestra attiva.

Si raccomanda di liberare le risorse dopo l'uso:

        Set oDoc = oDoc.Dispose()

In ogni caso, se il documento è stato chiuso usando il metodo CloseDocument, non si rende più necessario liberare le risorse usando il comando descritto sopra.

##### In Python

        myDoc = CreateScriptService("Calc")

        svcUI = CreateScriptService("UI")
        myDoc = svcUI.CreateDocument("Calc")

        myDoc = svcUI.OpenDocument(r"C:\Documents\MyFile.ods")

        myDoc = CreateScriptService("SFDocuments.Calc", "MyFile.ods")
        myDoc.Dispose()

L'uso del prefisso "SFDocuments." nella chiamata al servizio è opzionale.

## Definizioni

Molti metodi richiedono un "Foglio" o un "Area di celle" come argomento. Le celle singole sono considerate come un caso speciale di Area di celle.

Entrambi possono essere espressi sia come stringa o come riferimento (= oggetto) a seconda della situazione:

- All'interno di una specifica istanza di Calc, i fogli e le aree sono individuate da stringhe come "Foglio1" e "D2:F6".

- Inoltre, le proprietà .Sheet e .Range restituiscono un riferimento che può essere usato come argomento di un metodo chiamato da un'altra istanza del servizio Calc.

### Esempio:

L'esempio sottostante copia dati dal documento A (aperto in sola lettura e nascosto) al documento B.

##### In Basic

        Dim oDocA As Object, oDocB As Object
        Set oDocA = ui.OpenDocument("C:\Documents\FileA.ods", Hidden := True, ReadOnly := True)
        Set oDocB = ui.OpenDocument("C:\Documents\FileB.ods")
        oDocB.CopyToRange(oDocA.Range("SheetX.D4:F8"), "D2:F6") 'CopyToRange(source, target)

##### In Python

        docA = svcUI.OpenDocument(r"C:\Documents\FileA.ods", hidden = True, readonly = True)
        docB = svcUI.OpenDocument(r"C:\Documents\FileB.ods")
        docB.CopyToRange(docA.Range("SheetX.D4:F8"), "D2:F6")

### SheetName

Sia il nome del foglio come stringa o un oggetto creato dalla proprietà .Sheet.

La scorciatoia "~" (tilde) rappresenta il foglio corrente.

### RangeName

Sia una stringa che individua un insieme di celle contigue posizionate in un foglio dell'istanza corrente o un oggetto creato dalla proprietà .Range.

La scorciatoia "~" (tilde) rappresenta la selezione corrente o la prima area di celle selezionata, quando sono selezionate più aree.

La scorciatoia "*" rappresenta tutte le celle usate.

Il nome del foglio è opzionale per un'area (predefinito = il foglio attivo). Il suo inserimento tra virgolette singole e l'uso del simbolo $ sono permessi, ma vengono ignorati.

Ad eccezione della proprietà CurrentSelection, il servizio Calc considera solamente singole aree di celle.

Esempio di aree valide
1) '$FoglioX'.D2 2) $D$2 | Una cella singola
1) '$FoglioX'.D2:F6 2) D2:D10 | Una singola area con più celle
'$FoglioX'.* | Tutte le celle usate del foglio specificato
1) '$FoglioX'.A:A (colonna A) 2) 3:5 (righe da 3 a 5) | Tutte le celle di colonne o righe contigue fino all'ultima cella usata
miaArea | Un'area denominata "miaArea" a livello di foglio di calcolo
1) ~.unArea 2) FoglioX.unArea | Un nome di area a livello di foglio
myDoc.Range("FoglioX.D2:F6") | Un'area all'interno del foglio FoglioX nel file associato all'istanza myDoc di Calc
~.~ o ~ | La selezione corrente nel foglio attivo

## Proprietà

Tutte le proprietà generiche di ogni documento sono implicitamente applicabili anche ai documenti di Calc. Per maggiori informazioni, leggete la pagina dell'Aiuto in linea del servizio Document.

Le proprietà sono applicabili specificatamente ai documenti di Calc sono:

Nome | Sola lettura | Argomento | Tipo | Descrizione
CurrentSelection | No | Nessuno | Stringa o matrice di stringhe | L'unica area selezionata come stringa o una matrice con l'elenco delle aree selezionate
Height | Sì | NomeArea come Stringa | Long | Il numero di righe (>= 1) nell'area specificata
LastCell | Sì | NomeFoglio come stringa | String | L'ultima cella usata, in formato 'A1', nel foglio specificato
LastColumn | Sì | NomeFoglio come stringa | Long | L'ultima colonna usata nel foglio specificato
LastRow | Sì | NomeFoglio come stringa | Long | L'ultima riga usata nel foglio specificato
Range | Sì | NomeArea come Stringa | Object | Il riferimento a un'area che può essere usato come argomento di metodi come CopyToRange
Sheet | Sì | NomeFoglio come stringa | Object | Il riferimento a un foglio che può essere usato come argomento di metodi come CopySheet
Sheets | Sì | Nessuno | Matrice di stringhe | L'elenco dei nomi di tutti i fogli esistenti
Width | Sì | NomeArea come Stringa | Long | Il numero di colonne (>= 1) nell'area specificata
XCellRange | Sì | NomeArea come Stringa | Object | Un oggetto UNO com.sun.star.Table.XCellRange
XSpreadsheet | Sì | NomeFoglio come stringa | Object | Un oggetto UNO com.sun.star.sheet.XSpreadsheet

Visitate il sito di documentazione delle API di LibreOffice per saperne di più sugli oggetti UNO XCellRange e XSpreadsheet.

## Metodi

Elenco dei metodi del servizio Calc
Activate ClearAll ClearFormats ClearValues CopySheet CopySheetFromFile CopyToCell CopyToRange DAvg DCount | DMax DMin DSum Forms GetColumnName GetFormula GetValue ImportFromCSVFile ImportFromDatabase InsertSheet | MoveRange MoveSheet Offset RemoveSheet RenameSheet SetArray SetValue SetCellStyle SetFormula SortRange

## Activate

Se è fornito l'argomento SheetName, il foglio specificato viene attivato e diventa il foglio attualmente selezionato. Se l'argomento è assente, viene attivata la finestra del documento.

### Sintassi:

svc.Activate(sheetname: str = ""): bool

### Parametri:

sheetname: il nome del foglio da attivare nel documento. Il valore predefinito è una stringa vuota, ciò significa che verrà attivata la finestra del documento senza cambiare il foglio attivo.

### Esempio:

L'esempio seguente attiva il foglio denominato "Foglio4" nel documento attualmente attivo.

##### In Basic

        Dim ui as Variant, oDoc as Object
        Set ui = CreateScriptService("UI")
        Set oDoc = ui.GetDocument(ui.ActiveWindow)
        oDoc.Activate("Sheet4")

##### In Python

        svcUI = CreateScriptService("UI")
        myDoc = svcUI.GetDocument(svcUI.ActiveWindow)
        myDoc.Activate("Sheet4")

L'attivazione di un foglio ha senso solo se eseguita su di un documento di Calc. Per assicurarvi di avere a che fare con un documento di Calc potete a usare la proprietà isCalc dell'oggetto document, che restituisce True se il documento è di Calc e False in caso contrario.

## ClearAll

Vuota tutti i contenuti e i formati dell'area specificata.

### Sintassi:

svc.ClearAll(range: str)

### Parametri:

range: l'area da vuotare, in formato stringa.

### Esempio:

##### In Basic

          oDoc.ClearAll("SheetX.A1:F10")

##### In Python

        myDoc.ClearAll("SheetX.A1:F10")

## ClearFormats

Vuota tutti i formati e gli stili dell'area specificata.

### Sintassi:

svc.ClearFormats(range: str)

### Parametri:

range: l'area i cui formati e stili devono essere vuotati, in formato stringa.

### Esempio:

##### In Basic

          oDoc.ClearFormats("SheetX.*")

##### In Python

        myDoc.ClearFormats("SheetX.*")

## ClearValues

Vuota i valori e le formule nell'area specificata.

### Sintassi:

svc.ClearValues(range: str)

### Parametri:

range: l'area i cui valori e formule devono essere vuotati, in formato stringa.

### Esempio:

##### In Basic

          oDoc.ClearValues("SheetX.A1:F10")

##### In Python

        myDoc.ClearValues("SheetX.A1:F10")

## CopySheet

Copia il foglio specificato prima di un foglio esistente o alla fine dell'elenco dei fogli. Il foglio da copiare può essere contenuto in qualsiasi documento aperto di Calc. Restituisce True se l'operazione viene eseguita correttamente.

### Sintassi:

svc.CopySheet(sheetname: any, newname: str, [beforesheet: any]): bool

### Parametri:

sheetname: il nome del foglio da copiare in formato stringa o il suo riferimento come oggetto.

newname: il nome del foglio da inserire. Il nome non deve essere già in uso nel documento.

beforesheet: il nome (stringa) o l'indice (numerico, a partire da 1) del foglio prima del quale inserire il foglio copiato. Questo argomento è opzionale e il comportamento predefinito è quello di aggiungere il foglio nell'ultima posizione.

### Esempio:

##### In Basic

L'esempio seguente crea una copia del foglio "FoglioX" e la posiziona come ultimo foglio del documento corrente. Il nome del foglio risultante dalla copia è "FoglioY".

        Dim oDoc as Object
        'Ottiene l'oggetto Document della finestra attiva
        Set oDoc = CreateScriptService("Calc")
        oDoc.CopySheet("SheetX", "SheetY")

L'esempio seguente copia "FoglioX" dal file "FileA.ods" e lo incolla nell'ultima posizione del file "FileB.ods" con il nome "FoglioY":

          Dim oDocA As Object : Set oDocA = ui.OpenDocument("C:\Documents\FileA.ods", Hidden := True, ReadOnly := True)
          Dim oDocB As Object : Set oDocB = ui.OpenDocument("C:\Documents\FileB.ods")
          oDocB.CopySheet(oDocA.Sheet("SheetX"), "SheetY")

##### In Python

        myDoc.CopySheet("SheetX", "SheetY")

        docA = svcUI.OpenDocument(r"C:\Documents\FileA.ods", hidden = True, readonly = True)
        docB = svcUI.OpenDocument(r"C:\Documents\FileB.ods")
        docB.CopySheet(docA.Sheet("SheetX"), "SheetY")

Per copiare fogli tra documenti aperti, usate CopySheet. Per copiare fogli da documenti che sono chiusi, usate CopySheetFromFile.

## CopySheetFromFile

Copia il foglio specificato da un documento chiuso di Calc e lo incolla prima di un foglio esistente o alla fine dell'elenco dei fogli del file a cui fa riferimento l'oggetto Document.

Se il file non esiste, viene sollevato un errore. Se il file non è un file di Calc valido, viene inserito un foglio vuoto. Se il foglio da copiare non esiste nel file di partenza, viene inserito un messaggio di errore in cima al nuovo foglio appena incollato.

### Sintassi:

svc.CopySheetFromFile(filename: str, sheetname: str, newname: str, [beforesheet: any]): bool

### Parametri:

filename: identifica il file da aprire. Deve seguire la notazione SF_FileSystem.FileNaming. Il file non deve essere protetto da una password.

sheetname: il nome del foglio da copiare in formato stringa.

newname: il nome del foglio copiato da inserire nel documento. Il nome non deve essere già in uso nel documento.

beforesheet: Il nome (stringa) o l'indice (numerico, a partire da 1) del foglio prima del quale inserire il foglio copiato. Questo argomento è opzionale e il comportamento predefinito è quello di aggiungere il foglio nell'ultima posizione.

### Esempio:

L'esempio seguente copia "FoglioX" dal file "mioFile.ods" e lo incolla come "FoglioY" in prima posizione nel documento a cui fa riferimento "oDoc".

##### In Basic

        oDoc.CopySheetFromFile("C:\Documents\myFile.ods", "SheetX", "SheetY", 1)

##### In Python

        myDoc.CopySheetFromFile(r"C:\Documents\myFile.ods", "SheetX", "SheetY", 1)

## CopyToCell

Copia l'area di celle specificata (valori, formule e formati) in un'area o una cella di destinazione. Il metodo riproduce il comportamento dell'operazione di Copia/Incolla da un'area a una singola cella.

Restituisce una stringa che rappresenta l'area di celle modificate. Le dimensioni dell'area modificata sono determinate completamente dalle dimensioni dell'area di partenza.

L'area di partenza può appartenere a un altro documento aperto.

### Sintassi:

svc.CopyToCell(sourcerange: any, destinationcell: str): str

### Parametri:

sourcerange: l'area di partenza in formato stringa se appartiene allo stesso documento, o come riferimento se appartiene a un altro documento aperto di Calc.

destinationcell: la cella di destinazione nella quale sarà incollata l'area di celle copiate, in formato stringa. Se è specificata un'area, verrà considerata solo la sua prima cella in alto a sinistra.

### Esempio:

##### In Basic

Qui di seguito un esempio in cui sorgente e destinazione sono nello stesso file:

          oDoc.CopyToCell("SheetX.A1:F10", "SheetY.C5")

L'esempio sottostante illustra come copiare un'area da un altro documento aperto di Calc:

        Dim ui as Variant : ui = CreateScriptService("UI")
        Dim oDocSource As Object, oDocDestination As Object
        'Apre il documento sorgente in background (nascosto)
        Set oDocSource = ui.OpenDocument("C:\SourceFile.ods", Hidden := True, ReadOnly := True)
        Set oDocDestination = CreateScriptService("Calc")
        oDocDestination.CopyToCell(oDocSource.Range("Sheet1.C2:C4"), "SheetT.A5")
        'Non dimenticate di chiudere il documento sorgente, dato che è stato aperto come nascosto
        oDocSource.CloseDocument()

##### In Python

        docSource = svcUI.OpenDocument(r"C:\Documents\SourceFile.ods", hidden = True, readonly = True)
        docDestination = CreateScriptService("Calc")
        docDestination.CopyToCell(docSource.Range("Sheet1.C2:C4"), "SheetT.A5")
        docSource.CloseDocument()

Per simulare il Copia/Incolla da un'area a una singola cella, usate CopyToCell. Per simulare il Copia/Incolla da un'area a un'area più ampia (con le stesse celle ripetute più volte), usate CopyToRange.

## CopyToRange

Copia verso il basso e/o verso destra un'area specificata (valori, formule e formati) in un'area di destinazione. Il metodo imita il comportamento di un'operazione di Copia/Incolla da un'area di partenza a un'area di destinazione più ampia.

- Se l'altezza (o la larghezza) dell'area di destinazione è > 1 riga (o colonna), allora l'altezza (o la larghezza) della sorgente deve essere <= dell'altezza (o della larghezza) della destinazione. Altrimenti non succede nulla.

- Se l'altezza (o la larghezza) della destinazione è = 1 allora la destinazione si espande verso il basso (o verso destra) fino ad avere l'altezza (o la larghezza) dell'area di partenza.

Il metodo restituisce una stringa che rappresenta l'area di celle modificata.

L'area di partenza può appartenere a un altro documento aperto.

### Sintassi:

svc.CopyToRange(sourcerange: any, destinationrange: str): str

### Parametri:

sourcerange: L'area di partenza in formato stringa se appartiene allo stesso documento, o come riferimento se appartiene ad un altro documento aperto di Calc.

destinationrange: la destinazione dell'area di celle copiate, in formato stringa.

### Esempio:

##### In Basic

Copia all'interno dello stesso documento:

        oDoc.CopyToRange("SheetX.A1:F10", "SheetY.C5:J5")
        ' Restituisce l'area in formato stringa: "$FoglioY.$C$5:$J$14"

Copia da un file a un altro:

        Dim oDocA As Object : Set oDocA = ui.OpenDocument("C:\Documents\FileA.ods", Hidden := True, ReadOnly := True)
        Dim oDocB As Object : Set oDocB = ui.OpenDocument("C:\Documents\FileB.ods")
        oDocB.CopyToRange(oDocA.Range("SheetX.A1:F10"), "SheetY.C5:J5")

##### In Python

        doc.CopyToRange("FoglioX.A1:F10", "FoglioY.C5:J5")

        docA = svcUI.OpenDocument(r"C:\Documents\FileA.ods", hidden = True, readonly = True)
        docB = svcUI.OpenDocument(r"C:\Documents\FileB.ods")
        docB.CopyToRange(docA.Range("SheetX.A1:F10"), "SheetY.C5:J5")

## DAvg, DCount, DMax, DMin and DSum

Applica le funzioni Media, Conta, Max, Min e Somma, rispettivamente, a tutte le celle di una determinata area che contengono valori numerici.

### Sintassi:

svc.DAvg(range: str): float

svc.DCount(range: str): float

svc.DMax(range: str): float

svc.DMin(range: str): float

svc.DSum(range: str): float

### Parametri:

range: l'area sulla quale la funzione sarà applicata, in formato stringa.

### Esempio:

L'esempio sottostante applica la funzione Somma all'area "A1:A1000" del foglio correntemente selezionato:

##### In Basic

          result = oDoc.DSum("~.A1:A1000")

##### In Python

        result = myDoc.DSum("~.A1:A1000")

Le celle dell'area specificata che contengono testo saranno ignorate da tutte queste funzioni. Per esempio, il metodo DCount non conterà le celle di testo, solo quelle numeriche.

## Forms

A seconda dei parametri forniti questo metodo restituirà:

- Una matrice con indice di partenza zero (o una tupla in Python) con i nomi di tutti i formulari contenuti in un determinato foglio (se l'argomento form è assente)

- Un'istanza del servizio SFDocuments.Form che rappresenta il formulario specificato come argomento.

### Sintassi:

svc.Forms(sheetname: str): str[0..*]

svc.Forms(sheetname: str, form: str = ''): svc

svc.Forms(sheetname: str, form: int): svc

### Parametri:

sheetname: Il nome del foglio, in formato stringa, dal quale il formulario sarà recuperato.

form: il nome o l'indice corrispondente a un formulario memorizzato nel foglio specificato. Se questo argomento è assente, il metodo restituirà un elenco con i nomi di tutti i formulari disponibili nel foglio.

### Esempio:

Negli esempi seguenti la prima riga ricava i nomi di tutti i formulari memorizzati nel "Foglio1" e la seconda recupera l'oggetto Form del formulario denominato "Form_A" che è memorizzato nel "Foglio1".

##### In Basic

        Set FormNames = oDoc.Forms("Foglio1")
        Set FormA = oDoc.Forms("Foglio1", "Form_A")

##### In Python

        form_names = doc.Forms("Foglio1")
        form_A = doc.Forms("Foglio1", "Form_A")

## GetColumnName

Converte il numero di una colonna compreso tra 1 e 1024 nella lettera corrispondente (colonna 'A', 'B', ..., 'AMJ'). Se il numero di colonna specificato è al di fuori dell'intervallo ammesso, viene restituita una stringa di lunghezza pari a zero.

### Sintassi:

svc.GetColumnName(columnnumber: int): str

### Parametri:

columnnumber: il numero di colonna come numero intero nell'intervallo 1 ... 1024.

### Esempio:

##### In Basic

Visualizza una finestra di dialogo col nome della terza colonna, il cui valore predefinito è "C".

        MsgBox oDoc.GetColumnName(3)

##### In Python

        sBasic = CreateScriptService("Basic")
        sBasic.MsgBox(myDoc.GetColumnName(3))

Il numero massimo di colonne consentite in un foglio di Calc è 1024.

## GetFormula

Ottiene le formule memorizzate nell'area di celle specificata, in formato stringa singola, o matrice di stringhe a 1D o 2D.

### Sintassi:

svc.GetFormula(range: str): any

### Parametri:

range: l'area dalla quale recuperare le formule, in formato stringa.

### Esempio:

##### In Basic

Gli esempi che seguono restituiscono una matrice di 3 per 2 con le formule dell'area "A1:B3" (3 righe per 2 colonne):

        arrFormula = oDoc.GetFormula("~.A1:B3")

##### In Python

        arrFormula = myDoc.GetFormula("~.A1:B3")

## GetValue

Ricava i valori memorizzati nell'area di celle specificata come valore singolo, o come matrice a 1D o 2D. Tutti i valori sono numeri a precisione doppia o stringhe.

### Sintassi:

svc.GetValue(range: str): any

### Parametri:

range: l'area da cui ricavare i valori, in formato stringa.

### Esempio:

##### In Basic

          arrValues = oDoc.GetValue("~.B1:C100")

##### In Python

        arrValues = myDoc.GetValue("~.B1:C100")

Se una cella contiene una data, verrà restituito il numero corrispondente a quella data. Per convertire i valori numerici in date negli script in Basic, usate la funzione incorporata di Basic CDate. Negli script in Python, usate la funzione CDate del servizio Basic.

## ImportFromCSVFile

Importa i contenuti di un file di testo formattato come CSV e li inserisce nella cella di destinazione specificata.

L'area di destinazione viene vuotata di tutti i contenuti e formati prima dell'inserimento del contenuto del file CSV. La dimensione dell'area modificata dipende completamente dai contenuti del file inserito.

Il metodo restituisce una stringa che rappresenta l'area di celle modificate.

### Sintassi:

svc.ImportFromCSVFile(filename: str, destinationcell: str, [filteroptions: str]): str

### Parametri:

filename: identifica il file da aprire. Deve rispettare la notazione SF_FileSystem.FileNaming.

destinationcell: la cella di destinazione in cui inserire i dati importati, in formato stringa. Se invece viene specificata un'area, viene considerata solamente la sua prima cella in alto a sinistra.

filteroptions: gli argomenti per il filtro di importazione CSV. Il filtro predefinito presume quanto segue:

- La codifica del file importato è UTF8.

- Il separatore dei campi è la virgola, un punto e virgola o un carattere di tabulazione.

- Il delimitatore per le stringhe sono le virgolette (").

- Tutte le righe sono comprese.

- Le stringhe tra virgolette sono formattate come testo.

- I numeri speciali vengono riconosciuti.

- Si presume che tutte le colonne siano di testo, salvo che non siano riconosciute essere in un formato numerico valido.

- La lingua è l'inglese (US), il che comporta che il separatore dei decimali è "." e quello delle migliaia è ",".

### Esempio:

##### In Basic

        oDoc.ImportFromCSVFile("C:\Temp\myCSVFile.csv", "SheetY.C5")

##### In Python

        myDoc.ImportFromCSVFile(r"C:\Temp\myCSVFile.csv", "SheetY.C5")

Per saperne di più sulle opzioni del filtro CSV, fate riferimento alla pagina wiki sulle Opzioni dei filtri (in inglese).

## ImportFromDatabase

Importa i contenuti da un database prendendoli da una tabella, una query o un insieme di risultati, ad esempio i risultati di un comando SQL SELECT, e inserendoli in una cella di destinazione.

L'area di destinazione viene vuotata di tutti i contenuti e formati prima dell'inserimento dei contenuti importati. Le dimensioni dell'area modificata dipende completamente dai contenuti della tabella o della query.

Il metodo restituisce True, se l'importazione ha avuto successo.

### Sintassi:

svc.ImportFromDatabase(filename: str = "", registrationname: str = "", destinationcell: str = "", sqlcommand: str = "", directsql: bool): bool

### Parametri:

filename: Identifica il file da aprire. Deve rispettare la notazione SF_FileSystem.FileNaming.

registrationname: il nome da usare per individuare il database tra quelli registrati. Questo argomento viene ignorato se viene specificato un filename.

destinationcell: la destinazione dei dati importati, in formato stringa. Se viene specificata un'area, viene considerata solamente la sua prima cella in alto a sinistra.

sqlcommand: il nome di una tabella o di una query (senza virgolette o parentesi quadre) o un'istruzione SQL SELECT, nella quale i nomi di tabella e dei campi possono essere racchiusi tra parentesi quadre o virgolette al fine di migliorare la leggibilità.

directsql: se True, il comando SQL viene inviato al motore di database senza una pre-analisi. Il valore predefinito è False. L'argomento viene ignorato per le tabelle. Per le query, l'opzione applicata è una quella impostata al momento della creazione della query.

### Esempio:

##### In Basic

        oDoc.ImportFromDatabase("C:\Temp\myDbFile.odb", , "SheetY.C5", "SELECT * FROM [Employees] ORDER BY [LastName]")

##### In Python

        myDoc.ImportFromDatabase(r"C:\Temp\myDbFile.odb", , "SheetY.C5", "SELECT * FROM [Employees] ORDER BY [LastName]")

## InsertSheet

Inserisce un nuovo foglio vuoto prima di un foglio esistente o alla fine dell'elenco dei fogli.

### Sintassi:

svc.InsertSheet(sheetname: str, [beforesheet: any]): bool

### Parametri:

sheetname: il nome del nuovo foglio.

beforesheet: il nome (stringa) o l'indice (numerico, a partire da 1) del foglio prima del quale inserire il nuovo foglio. Questo argomento è opzionale e il comportamento predefinito è quello di inserire un foglio nell'ultima posizione.

### Esempio:

L'esempio seguente inserisce un nuovo foglio vuoto denominato "FoglioX" e lo posiziona prima del "FoglioY":

##### In Basic

        oDoc.InsertSheet("SheetX", "SheetY")

##### In Python

        myDoc.InsertSheet("SheetX", "SheetY")

## MoveRange

Sposta l'area di celle di partenza specificata in un'area di destinazione. Il metodo restituisce una stringa che rappresenta l'area di celle modificata. Le dimensioni dell'area modificata è totalmente determinata dalle dimensioni dell'area di partenza.

### Sintassi:

svc.MoveRange(source: str, destination: str): str

### Parametri:

source: l'area di celle di partenza, in formato stringa.

destination: la cella di destinazione, in formato stringa. Se viene specificata un'area, viene considerata come destinazione la sua prima cella in alto a sinistra.

### Esempio:

##### In Basic

        oDoc.MoveRange("SheetX.A1:F10", "SheetY.C5")

##### In Python

        myDoc.MoveRange("SheetX.A1:F10", "SheetY.C5")

## MoveSheet

Sposta un foglio esistente e lo posiziona prima di un determinato foglio, o alla fine dell'elenco dei fogli.

### Sintassi:

svc.MoveSheet(sheetname: str, [beforesheet: any]): bool

### Parametri:

sheetname: il nome del foglio da spostare. Il foglio deve esistere, altrimenti si genera un'eccezione.

beforesheet: il nome (stringa) o l'indice (numerico, a partire da 1) del foglio prima del quale verrà posizionato il foglio originale. Questo argomento è opzionale e il comportamento predefinito è quello di spostare il foglio all'ultima posizione.

### Esempio:

L'esempio seguente sposta il foglio esistente "FoglioX" e lo posiziona prima del "FoglioY":

##### In Basic

        oDoc.MoveSheet("SheetX", "SheetY")

##### In Python

        myDoc.MoveSheet("SheetX", "SheetY")

## Offset

Restituisce una nuova area (in formato stringa) spostata di un determinato numero di righe e colonne rispetto all'area specificata.

Questo metodo ha lo stesso comportamento della funzione Scarto di Calc.

### Sintassi:

svc.Offset(reference: str, rows: int = 0, columns: int = 0, [height: int], [width: int]): str

### Parametri:

reference: l'area, in formato stringa, che il metodo userà come riferimento per eseguire l'operazione di "scarto".

rows: il numero di righe di cui l'area iniziale è spostata in alto (valore negativo), o in basso (valore positivo). Usate 0 (predefinito) per rimanere nella stessa riga.

columns: il numero di colonne di cui l'area iniziale è spostata a sinistra (valore negativo), o a destra (valore positivo). Usate 0 (predefinito) per rimanere nella stessa colonna.

height: l'altezza verticale per un'area che inizia dalla nuova posizione dell'area. Omettete questo argomento se non è necessario alcun ridimensionamento verticale.

width: la larghezza orizzontale per un'area che inizia dalla nuova posizione dell'area. Omettete questo argomento se non è necessario alcun ridimensionamento orizzontale.

Gli argomenti righe e colonne non devono condurre a un inizio di riga o colonna pari a zero o negativo.

Gli argomenti altezza e larghezza non devono condurre a un conteggio di righe o colonne pari a zero o negativo.

### Esempio:

##### In Basic

        oDoc.Offset("A1", 2, 2)
        'FoglioX.$C$3 (A1 spostato in basso di due righe e due colonne)
        oDoc.Offset("A1", 2, 2, 5, 6)
        'FoglioX.$C$3:$H$7 (A1 spostato di due righe e colonne con una larghezza di 5 righe e 6 colonne)

##### In Python

        myDoc.Offset("A1", 2, 2)
        myDoc.Offset("A1", 2, 2, 5, 6)

## RemoveSheet

Elimina un foglio esistente dal documento.

### Sintassi:

svc.RemoveSheet(sheetname: str): bool

### Parametri:

sheetname: il nome del foglio da eliminare.

### Esempio:

##### In Basic

        oDoc.RemoveSheet("SheetY")

##### In Python

        myDoc.RemoveSheet("SheetY")

## RenameSheet

Rinomina il foglio specificato e restituisce True se l'operazione va a buon fine.

### Sintassi:

svc.RenameSheet(sheetname: str, newname: str): bool

### Parametri:

sheetname: il nome del foglio da rinominare.

newname: il nuovo nome del foglio. Non deve essere esistere già.

### Esempio:

Questo esempio rinomina in "FoglioY" il foglio attivo:

##### In Basic

        oDoc.RenameSheet("~", "SheetY")

##### In Python

        mydoc.RenameSheet("~", "SheetY")

## SetArray

Memorizza il valore indicato a partire dalla cella di destinazione specificata. L'area aggiornata si espande dalla cella di destinazione o dall'angolo in alto a sinistra dell'area indicata al fine di adeguarsi alle dimensioni dell'argomento inserito come valore. I vettori si espandono sempre verticalmente.

Il metodo restituisce una stringa che rappresenta l'area modificata come un intervallo di celle.

### Sintassi:

svc.SetArray(targetcell: str, value: any): str

### Parametri:

targetcell: la cella o l'area, in formato stringa, dalla quale iniziare a memorizzare il valore indicato.

value: uno scalare, un vettore o una matrice (in Python, liste e tuple a una o due dimensioni) con i nuovi valori da memorizzare a partire dalla cella di destinazione o dall'angolo in alto a sinistra dell'intervallo di celle quando targetcell è un'area. I nuovi valori devono essere stringhe, valori numerici o date. Altri tipi comporteranno lo svuotamento delle celle corrispondenti.

### Esempio:

##### In Basic

Il seguente esempio fa uso della funzione incorporata DimArray per creare una matrice e poi memorizzarla nella cella "A1":

        Dim arrData as Variant
        arrData = DimArray(2, 1)
        arrData(0, 0) = 1 : arrData(1, 0) = 2 : arrData(2, 0) = 3
        arrData(0, 1) = "One" : arrData(1, 1) = "Two" : arrData(2, 1) = "Three"
        oDoc.SetArray("Sheet1.A1", arrData)

Questo esempio usa il metodo RangeInit del servizio Array di ScriptForge per creare una matrice con i valori da memorizzare poi a partire dalla cella "A1" verso il basso.

        'Riempie la prima colonna con valori da 1 a 1000
        oDoc.SetArray("Sheet1.A1", SF_Array.RangeInit(1, 1000))

##### In Python

        arrData = ((1, "One"), (2, "Two"), (3, "Three"))
        myDoc.SetArray("Sheet1.A1", arrData)

        myDoc.SetArray("Sheet1.A1", tuple(i + 1 for i in range(1000)))

Per salvare l'intero contenuto di una matrice in un foglio, usate SetArray. Per salvare i contenuti di una matrice solo entro i limiti dell'intervallo di celle di destinazione, usate SetValue.

## SetValue

Memorizza il valore indicato nell'area specificata. Le dimensioni dell'area modificata sono uguali alle dimensioni dell'area di destinazione.

Il metodo restituisce una stringa che rappresenta l'area modificata come un intervallo di celle.

### Sintassi:

svc.SetValue(targetrange: str, value: any): str

### Parametri:

targetrange: l'area in cui memorizzare il valore indicato, in formato stringa.

value: uno scalare, un vettore o una matrice con i nuovi valori per ciascuna cella dell'area. I nuovi valori devono essere stringhe, valori numerici o date. Altri tipi comporteranno lo svuotamento delle celle corrispondenti.

L'intera area viene aggiornata e il resto del foglio non viene modificato. Se le dimensioni di value sono inferiori a quelle di targetrange, le celle rimanenti saranno vuotate.

Se la dimensione di value è maggiore di quella di targetrange, allora value viene copiato solo parzialmente fino a riempire la dimensione di targetrange.

I Vettori si estendono verticalmente, eccetto quando targetrange ha un'altezza pari esattamente a una riga.

### Esempio:

##### In Basic

        oDoc.SetValue("A1", 2)
        'Qui sotto la matrice Value è più piccola di TargetRange (le celle rimanenti vengono svuotate)
        oDoc.SetValue("A1:F1", Array(1, 2, 3))
        'Qui sotto Value e TargetRange hanno le stesse dimensioni
        oDoc.SetValue("A1:D2", SF_Array.AppendRow(Array(1, 2, 3, 4), Array(5, 6, 7, 8)))

Se volete riempire una singola riga con dei valori, potete usare la funzione Offset. Nell'esempio seguente, considerate che arrData è una matrice unidimensionale:

        Dim firstCell As String : firstCell = "A1"
        Dim lenArray As Integer : lenArray = UBound(arrData) - LBound(arrData) + 1
        Dim newRange As String : newRange = oDoc.Offset(firstCell, width = lenArray)
        oDoc.SetValue(newRange, arrData)

##### In Python

        myDoc.SetValue("A1", 2)
        myDoc.SetValue("A1:F1", (1, 2, 3))
        myDoc.SetValue("A1:D2", ((1, 2, 3, 4), (5, 6, 7, 8)))

        firstCell = "A1"
        newRange = doc.Offset(firstCell, width = len(arrData))
        doc.SetValue(newRange, arrData)

## SetCellStyle

Applica lo stile di cella specificato all'area di destinazione indicata. L'intera area viene aggiornata e il resto del foglio non viene modificato. Se lo stile di cella non esiste, viene generato un errore.

Il metodo restituisce una stringa che rappresenta l'area modificata come un intervallo di celle.

### Sintassi:

svc.SetCellStyle(targetrange: str, style: str): str

### Parametri:

targetrange: l'area a cui sarà applicato lo stile, in formato stringa.

style: il nome dello stile di cella da applicare.

### Esempio:

##### In Basic

        oDoc.SetCellStyle("A1:J1", "Heading 1")
        oDoc.SetCellStyle("A2:J100", "Neutral")

##### In Python

        myDoc.SetCellStyle("A1:J1", "Heading 1")
        myDoc.SetCellStyle("A2:J100", "Neutral")

## SetFormula

Inserisce la formula (o la matrice di formule) precisata nell'intervallo di celle specificato. Le dimensioni dell'area modificata sono uguali a quelle dell'intervallo di celle.

Il metodo restituisce una stringa che rappresenta l'area modificata come un intervallo di celle.

### Sintassi:

svc.SetFormula(targetrange: str, formula: any): str

### Parametri:

targetrange: l'intervallo di celle in cui inserire le formule, in formato stringa.

formula: una stringa, un vettore o una matrice di stringhe con le nuove formule per ciascuna delle celle nell'area di destinazione.

L'intera area viene aggiornata e il resto del foglio non viene modificato.

Se la formula indicata è una stringa, quella singola formula viene copiata in tutta l'area con la regolazione dei riferimenti relativi.

Se la dimensione di formula è inferiore a quella di targetrange, le celle rimanenti vengono svuotate.

Se la dimensione di formula è maggiore di quella di targetrange, le formule sono copiate solo parzialmente fino a riempire la dimensione di targetrange.

I Vettori si estendono sempre in verticale, eccetto quando targetrange ha un'altezza pari esattamente a una riga.

### Esempio:

##### In Basic

        oDoc.SetFormula("A1", "=A2")
        'Vettore orizzontale, parzialmente vuoto
        oDoc.SetFormula("A1:F1", Array("=A2", "=B2", "=C2+10"))
        'D2 contiene la formula "=H2"
        oDoc.SetFormula("A1:D2", "=E1")

##### In Python

        myDoc.SetFormula("A1", "=A2")
        myDoc.SetFormula("A1:F1", ("=A2", "=B2", "=C2+10"))
        myDoc.SetFormula("A1:D2", "=E1")

## SortRange

Ordina l'intervallo di celle indicato in base a un massimo di tre colonne/righe. Il tipo di ordinamento può variare per colonna/riga. Restituisce una stringa che rappresenta l'area modificata. La dimensione dell'area modificata è determinata interamente da quella dell'area di partenza.

### Sintassi:

svc.SortRange(range: str, sortkeys: any, sortorder: any = "ASC", destinationcell: str = "", containsheader: bool = False, casesensitive: bool = False, sortcolumns: bool = False): str

### Parametri:

range: l'area da ordinare, in formato stringa.

sortkeys: uno scalare (se di una colonna/riga) o una matrice di colonne/righe numerate a partire da 1. Il numero massimo di chiavi è 3.

sortorder: uno scalare o una matrice di stringhe che contiene i valori "ASC" (ascendente), "DESC" (discendente) o "" (per il valore predefinito ascendente). Ogni elemento è accoppiato al corrispondente in sortkeys. Se sortorder è una matrice più corta di sortkeys, le chiavi rimanenti vengono ordinate in modo ascendente.

destinationcell: la cella di destinazione per l'intervallo di celle riordinate, in formato stringa. Se è indicata un'area, viene considerata solo la cella nell'angolo in alto a sinistra. Per impostazione predefinita viene sovrascritta l'area di partenza.

containsheader: quando è True, la prima riga/colonna non viene riordinata.

casesensitive: solo per il confronto di stringhe. Predefinito = False

sortcolumns: quando è True, le colonne sono riordinate da sinistra a destra. Predefinito = False : le righe sono riordinate dall'alto verso il basso.

### Esempio:

##### In Basic

        'Ordina un'area in base alle colonne A (ascendente) e C (discendente)
        oDoc.SortRange("A2:J200", Array(1, 3), Array("ASC", "DESC"), CaseSensitive := True)

##### In Python

        myDoc.SortRange("A2:J200", (1, 3), ("ASC", "DESC"), casesensitive = True)

Tutte le routine e gli identificatori Basic di ScriptForge che iniziano con un carattere di sottolineatura "_" sono riservati per uso interno. Non è previsto il loro utilizzo nelle macro in Basic.

Argomenti correlati

Servizio SFDocuments.Document

Servizio ScriptForge.UI