Contenuto

# Servizio SFDocuments.Calc

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

Il servizio SFDocuments.Calc è una sottoclasse del servizio SFDocuments.Document. Potete accedere a tutti i metodi e le proprietà definiti per il servizio Document anche usando un'istanza del servizio Calc.

Il servizio 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

- Formattazione di semplici intervalli di celle

Questa pagina della guida descrive i metodi e le proprietà applicabili solamente ai documenti di Calc.

## Invocazione del servizio

Prima di usare il servizio Calc è necessario caricare o importare la libreria ScriptForge:

• Le macro in Basic richiedono il caricamento della libreria ScriptForge usando la seguente istruzione:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
• Gli script in Python richiedono un'importazione dal modulo scriptforge:
from scriptforge import CreateScriptService

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 specificando il nome di una finestra per 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.

È possibile invocare il servizio Calc anche usando il documento a cui fa riferimento ThisComponent. Questo è particolarmente utile quando si esegue una macro dall'interno dell'IDE Basic.

        Dim oDoc As Object
        Set oDoc = CreateScriptService("Calc", ThisComponent)

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")

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

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

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

        bas = CreateScriptService("Basic")
        myDoc = CreateScriptService("Calc", bas.ThisComponent)

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 = ui.OpenDocument(r"C:\Documents\FileA.ods", hidden = True, readonly = True)
        docB = ui.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 quando si definisce un intervallo. Se non è specificato il nome del foglio, viene usato il foglio attivo. I simboli delle virgolette semplici e del dollaro ($) sono ammessi, ma vengono ignorati.

Quando si specifica il nome del foglio SheetName in formato stringa, l'uso delle virgolette semplici per racchiudere il nome del foglio è necessario se il nome contiene degli spazi bianchi " " o dei punti ".".

Gli esempi sottostanti illustrano in quali casi l'uso delle virgolette semplici è obbligatorio:

          ' L'uso delle virgolette semplici è opzionale
          oDoc.clearAll("SheetA.A1:B10")
          oDoc.clearAll("'SheetA'.A1:B10")
          ' L'uso delle virgolette semplici è necessario
          oDoc.clearAll("'Sheet.A'.A1:B10")

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

Esempio di aree valide
1) $'SheetX'.D2 2) $D$2 | Una cella singola
1) $'SheetX'.D2:F6 2) D2:D10 | Una singola area con più celle
$'SheetX'.* | Tutte le celle usate del foglio specificato
1) $'SheetX'.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) ~.un'Area 2) SheetX.un'Area | Un nome di area a livello di foglio
myDoc.Range("SheetX.D2:F6") | Un'area all'interno del foglio SheetX 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 di dato restituito | Descrizione
--- | --- | --- | --- | ---
CurrentSelection | No | Nessuno | Stringa o matrice di stringhe | L'unica area selezionata come stringa o una matrice con l'elenco delle aree selezionate.
DefinedNames | Sì | Nessuno | Stringa o matrice di stringhe | Restituisce l'elenco ordinato e completo di tutti i nomi degli intervalli presenti nel documento. I nomi definiti in un singolo foglio vengono qualificati con il nome del foglio.
FirstCell | Sì | Il valore di SheetName (nome del foglio) o RangeName (nome dell'area) in formato stringa | String | Restituisce la prima cella occupata nell'area o nel foglio specificati.
FirstColumn | Sì | Il valore di SheetName (nome del foglio) o RangeName (nome dell'area) in formato stringa | Long | Restituisce il numero della colonna più a sinistra in un determinato intervallo o foglio.
FirstRow | Sì | Il valore di SheetName (nome del foglio) o RangeName (nome dell'area) in formato stringa | Long | Restituisce il numero di riga più in alto in una determinata area o foglio.
Height | Sì | RangeName As String | Long | Il numero di righe (>= 1) nell'area specificata.
LastCell | Sì | Il valore di SheetName (nome del foglio) o RangeName (nome dell'area) in formato stringa | String | Restituisce l'ultima cella occupata nell'area o nel foglio specificati.
LastColumn | Sì | Il valore di SheetName (nome del foglio) o RangeName (nome dell'area) in formato stringa | Long | L'ultima colonna occupata nell'area o nel foglio specificato.
LastRow | Sì | Il valore di SheetName (nome del foglio) o RangeName (nome dell'area) in formato stringa | Long | L'ultima riga occupata nell'area o nel foglio specificati.
Range | Sì | RangeName As String | Object | Il riferimento a un'area che può essere usato come argomento di metodi come CopyToRange.
Region | Sì | RangeName As String | String | Restituisce l'indirizzo dell'area più piccola in grado di contenere l'intervallo indicato, in modo che l'area sia circondata da celle vuote o dai margini del foglio. È equivalente all'applicazione della combinazione di tasti Cmd + *Ctrl + * sull'intervallo in questione.
Sheet | Sì | NomeFoglio come stringa | Object | Il riferimento a un foglio che può essere usato come argomento di metodi come CopySheet.
SheetName | Sì | RangeName As String | String | Restituisce il nome del foglio di un determinato intervallo.
Sheets | Sì | Nessuno | Matrice di stringhe | L'elenco dei nomi di tutti i fogli esistenti.
Width | Sì | RangeName As String | Long | Il numero di colonne (>= 1) nell'area specificata.
XCellRange | Sì | RangeName As String | Object | Un oggetto UNO com.sun.star.Table.XCellRange.
XRectangle | Sì | RangeName As String | Object | Una struttura UNO com.sun.star.awt.Rectangle, che descrive, in pixel, l'area sullo schermo in cui si trova l'intervallo.
XSheetCellCursor | Sì | RangeName As String | Object | Un oggetto UNO com.sun.star.sheet.XSheetCellCursor. Dopo aver spostato il cursore, potete accedere all'indirizzo dell'intervallo di celle risultante tramite la proprietà AbsoluteName UNO dell'oggetto cursore, la quale restituisce una stringa utilizzabile come argomento per le proprietà e i metodi del servizio Calc.
XSpreadsheet | Sì | NomeFoglio come stringa | Object | Un oggetto UNO com.sun.star.sheet.XSpreadsheet.

Visitare il sito della Documentazione delle API di LibreOffice per saperne di più sugli oggetti UNO XCellRange, XSheetCellCursor e XSpreadsheet.

## Metodi

Elenco dei metodi del servizio Calc
A1Style Activate AlignRange BorderRange Charts ClearAll ClearFormats ClearValues ColorizeRange CompactLeft CompactUp CopySheet CopySheetFromFile CopyToCell CopyToRange CreateChart CreatePivotTable DAvg | DCount DecorateFont DefineName DMax DMin DSum ExportRangeToFile FormatRange Forms GetColumnName GetFormula GetValue ImportFromCSVFile ImportFromDatabase ImportStylesFromFile InsertSheet Intersect MoveRange | MoveSheet Offset OpenRangeSelector PrintOut Printf RemoveDuplicates RemoveSheet RenameSheet SetArray SetCellStyle SetFormula SetValue ShiftDown ShiftLeft ShiftRight ShiftUp SortRange

## A1Style

Restituisce l'indirizzo di un intervallo in formato stringa basato sulle coordinate del foglio, ad es. numeri di riga e colonna.

Se vengono inserite solo un paio di coordinate, sarà restituito solo l'indirizzo di una singola cella. Degli argomenti aggiuntivi possono specificare la cella inferiore destra di un intervallo rettangolare.

### Sintassi:

svc.A1Style(row1: int, column1: int, row2: int = 0; column2: int = 0; sheetname: str = "~"): str

### Parametri:

row1, column1: specifica i numeri di riga e colonna della cella superiore sinistra nell'intervallo da considerare. I numeri di riga e colonna iniziano da 1.

row2, column2: specifica i numeri di riga e colonna della cella inferiore destra nell'intervallo da considerare. Se questi argomenti non sono inseriti, o se i loro valori sono inferiori a quelli di row1 e column1, verrà restituito l'indirizzo dell'intervallo rappresentato dalla singola cella row1 e column1.

sheetname: il nome del foglio da aggiungere all'intervallo di celle restituito. Il foglio deve esistere. Il valore predefinito è "~" che corrisponde al foglio attualmente attivo.

### Esempio:

Gli esempi sottostanti in Basic e Python considerano che "Sheet1" sia il foglio attualmente attivo.

##### In Basic

        Set oDoc = CreateScriptService("Calc")
        addr1 = oDoc.A1Style(1, 1) ' '$Sheet1'.$A$1
        addr2 = oDoc.A1Style(2, 2, 3, 6) ' '$Sheet1'.$B$2:$F$3
        addr3 = oDoc.A1Style(2, 2, 0, 6) ' '$Sheet1'.$B$2
        addr4 = oDoc.A1Style(3, 4, 3, 8, "Sheet2") ' '$Sheet2'.$D$3:$H$3
        addr5 = oDoc.A1Style(5, 1, SheetName := "Sheet3") ' '$Sheet3'.$A$5

##### In Python

        doc = CreateScriptService("Calc")
        addr1 = doc.A1Style(1, 1) # '$Sheet1'.$A$1
        addr2 = doc.A1Style(2, 2, 3, 6) # '$Sheet1'.$B$2:$F$3
        addr3 = doc.A1Style(2, 2, 0, 6) # '$Sheet1'.$B$2
        addr4 = doc.A1Style(3, 4, 3, 8, "Sheet2") # '$Sheet2'.$D$3:$H$3
        addr5 = doc.A1Style(5, 1, sheetname="Sheet3") # '$Sheet3'.$A$5

Il metodo A1Style può essere combinato con qualsiasi proprietà e metodo del servizio Calc che richieda un intervallo come argomento, come GetValue, GetFormula, ClearAll, ecc.

## 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

        ui = CreateScriptService("UI")
        myDoc = ui.GetDocument(ui.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.

## AlignRange

Allinea orizzontalmente o verticalmente un intervallo di celle.

Può essere specificata una formula di filtro per determinare quali celle devono essere coinvolte.

### Sintassi:

svc.AlignRange(targetrange: str, alignment: str, opt filterformula: str, opt filterscope: str)

### Parametri:

targetrange: la cella o l'intervallo in forma di stringa in cui le celle devono essere riallineate.

alignment: una stringa che combina uno o due dei seguenti caratteri maiuscoli (gli altri caratteri vengono ignorati):

- L, R o C: sinistra, destra o al centro orizzontalmente.

- B, T o M: in basso, in alto o al centro verticalmente (in mezzo).

filterformula: una formula di Calc da applicare all'area indicata per determinare quali celle saranno coinvolte. La formula specificata deve restituire True o False. Se questo argomento non è specificato, saranno coinvolte tutte le celle dell'area.

filterscope: determina come filterformula si estende all'area indicata. Questo argomento è obbligatorio se è stato specificato l'argomento filterformula. Sono ammessi i seguenti valori:

- "CELL": la formula indicata nell'argomento filterformula si espande una volta per ogni cella nell'area range.

- "ROW": la formula specificata nell'argomento filterformula si espande una volta per ogni riga nell'area range.

- "COLUMN": la formula specificata nell'argomento filterformula si espande una volta per ogni colonna nell'area range.

### Esempio:

##### In Basic

          ' Centra tutte le celle numeriche, sia orizzontalmente che verticalmente.
          doc.AlignRange("SheetX.A1:J30", "Middle,Center", filterformula := "=IsNumeric(A1)", filterscope := "CELL")

##### In Python

          # Centra tutte le celle numeriche, sia orizzontalmente che verticalmente.
          doc.AlignRange('SheetX.A1:J30', 'Middle,Center', filterformula = '=IsNumeric(A1)', filterscope = 'CELL')

## BorderRange

Applica all'interno e attorno a un intervallo di celle un insieme di linee sui bordi.

Le celle influenzate possono essere determinate con una formula di filtro e dal suo ambito.

Tutti i bordi hanno lo stesso spessore, stile e colore standard. Le linee dei bordi preesistenti nelle celle, righe e colonne interessate vengono prima cancellate. Le altre celle nell'intervallo non vengono modificate.

Per cancellare tutti i bordi dall'intero intervallo, impostare border a "" e omettere l'argomento filterformula.

### Sintassi:

svc.BorderRange(targetrange: str, border: str, opt filterformula: str, opt filterscope: str)

### Parametri:

targetrange: la cella o l'intervallo in forma di stringa su cui devono essere applicati i bordi.

border: una stringa che combina i seguenti caratteri maiuscoli (gli altri caratteri vengono ignorati):

- B, L, T, R: linee esterne in basso, a sinistra, in alto, a destra.

- H, V: linee interne orizzontali, verticali.

- U, D: diagonali dal basso in alto, dall'alto in basso.

filterformula: una formula di Calc da applicare all'area indicata per determinare quali celle saranno coinvolte. La formula specificata deve restituire True o False. Se questo argomento non è specificato, saranno coinvolte tutte le celle dell'area.

filterscope: determina come filterformula si estende all'area indicata. Questo argomento è obbligatorio se è stato specificato l'argomento filterformula. Sono ammessi i seguenti valori:

- "CELL": la formula indicata nell'argomento filterformula si espande una volta per ogni cella nell'area range.

- "ROW": la formula specificata nell'argomento filterformula si espande una volta per ogni riga nell'area range.

- "COLUMN": la formula specificata nell'argomento filterformula si espande una volta per ogni colonna nell'area range.

### Esempio:

##### In Basic

            ' Mette un bordo a tutte le celle numeriche con una linea in basso, comprese le righe orizzontali interne.
            doc.BorderRange("SheetX.A1:J30", "HB", filterformula := "=IsNumeric(A1)", filterscope := "CELL")

##### In Python

            # Mette un bordo a tutte le celle numeriche con una linea in basso, comprese le righe orizzontali interne.
            doc.BorderRange('SheetX.A1:J30', 'HB', filterformula = '=IsNumeric(A1)', filterscope = 'CELL')

## Charts

Restituisce l'elenco con i nomi di tutti gli oggetti grafici del foglio precisato, o una singola istanza del servizio Chart.

- Se è specificato solo sheetname, viene restituita una matrice con indice a partire da zero che contiene i nomi di tutti i grafici.

- Se è inserito un chartname, viene restituito un singolo oggetto corrispondente al grafico desiderato. Il grafico specificato deve esistere.

### Sintassi:

svc.Charts(sheetname: str, chartname: str = ""): obj

### Parametri:

sheetname: il nome del foglio da cui recuperare l'elenco dei grafici, o nel quale si trova il grafico specificato.

chartname: il nome definito dall'utente dell'oggetto rappresentante il grafico da restituire. Se il grafico non possiede un nome definito dall'utente, potete usare il nome interno dell'oggetto. Se l'argomento è assente, viene restituito l'elenco di tutti i nomi dei grafici presenti nel foglio specificato.

Per controllare i nomi assegnati ai grafici all'interno della categoria Oggetti OLE utilizzate il Navigatore nella barra laterale.

### Esempio:

##### In Basic

L'esempio sottostante mostra il numero di oggetti grafici presenti in "Sheet1".

        Dim arrNames as Object
        arrNames = oDoc.Charts("Sheet1")
        MsgBox "There are " & UBound(arrNames) + 1 & " charts in Sheet1"

L'esempio seguente accede al grafico denominato "MyChart" in "Sheet1" e restituisce il suo tipo.

        Dim oChart as Object
        oChart = oDoc.Charts("Sheet1", "MyChart")
        MsgBox oChart.ChartType

##### In Python

        bas = CreateScriptService("Basic")
        chart_names = doc.Charts("Sheet1")
        bas.MsgBox(f"There are {len(chart_names)} charts in Sheet1")

        chart = doc.Charts("Sheet1", "MyChart")
        bas.MsgBox(chart.ChartType)

## ClearAll

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

Può essere specificata una formula di filtro per determinare quali celle devono essere coinvolte.

### Sintassi:

svc.ClearAll(range: str, opt filterformula: str, opt filterscope: str)

### Parametri:

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

filterformula: una formula di Calc da applicare all'area indicata per determinare quali celle saranno coinvolte. La formula specificata deve restituire True o False. Se questo argomento non è specificato, saranno coinvolte tutte le celle dell'area.

filterscope: determina come filterformula si estende all'area indicata. Questo argomento è obbligatorio se è stato specificato l'argomento filterformula. Sono ammessi i seguenti valori:

- "CELL": la formula indicata nell'argomento filterformula si espande una volta per ogni cella nell'area range.

- "ROW": la formula specificata nell'argomento filterformula si espande una volta per ogni riga nell'area range.

- "COLUMN": la formula specificata nell'argomento filterformula si espande una volta per ogni colonna nell'area range.

### Esempio:

##### In Basic

        ' Vuota tutte le celle nell'area SheetX.A1:J10
        oDoc.ClearAll("SheetX.A1:J10")
        ' Vuota tutte le celle nell'area SheetX.A1:J10 che hanno un valore maggiore di 100
        oDoc.ClearAll("SheetX.A1:J10", "=SheetX.A1>100", "CELL")
        ' Vuota tutte le righe nell'area SheetX.A1:J10 la cui somma è maggiore di 500
        oDoc.ClearAll("SheetX.A1:J10", "=SUM(SheetX.A1:J1)>500", "ROW")
        ' Vuota tutte le colonne nell'area SheetX.A1:J10 la cui somma è maggiore di 500
        oDoc.ClearAll("SheetX.A1:J10", "=SUM(SheetX.A1:A10)>500", "COLUMN")

##### In Python

        myDoc.ClearAll("SheetX.A1:F10")
        myDoc.ClearAll("SheetX.A1:J10", "=SheetX.A1>100", "CELL")
        myDoc.ClearAll("SheetX.A1:J10", "=SUM(SheetX.A1:J1)>500", "ROW")
        myDoc.ClearAll("SheetX.A1:J10", "=SUM(SheetX.A1:A10)>500", "COLUMN")

## ClearFormats

Cancella tutti i formati e gli stili nell'intervallo specificato.

Può essere specificata una formula di filtro per determinare quali celle devono essere coinvolte.

### Sintassi:

svc.ClearFormats(range: str, opt filterformula: str, opt filterscope: str)

### Parametri:

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

filterformula: una formula di Calc da applicare all'area indicata per determinare quali celle saranno coinvolte. La formula specificata deve restituire True o False. Se questo argomento non è specificato, saranno coinvolte tutte le celle dell'area.

filterscope: determina come filterformula si estende all'area indicata. Questo argomento è obbligatorio se è stato specificato l'argomento filterformula. Sono ammessi i seguenti valori:

- "CELL": la formula indicata nell'argomento filterformula si espande una volta per ogni cella nell'area range.

- "ROW": la formula specificata nell'argomento filterformula si espande una volta per ogni riga nell'area range.

- "COLUMN": la formula specificata nell'argomento filterformula si espande una volta per ogni colonna nell'area range.

### Esempio:

##### In Basic

          oDoc.ClearFormats("SheetX.*")

##### In Python

        myDoc.ClearFormats("SheetX.*")

Per degli esempi su come usare gli argomenti filterformula e filterscope fare riferimento alla documentazione, disponibile sopra, del metodo ClearAll.

## ClearValues

Vuota i valori e le formule nell'area specificata.

Può essere specificata una formula di filtro per determinare quali celle devono essere coinvolte.

### Sintassi:

svc.ClearValues(range: str, opt filterformula: str, opt filterscope: str)

### Parametri:

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

filterformula: una formula di Calc da applicare all'area indicata per determinare quali celle saranno coinvolte. La formula specificata deve restituire True o False. Se questo argomento non è specificato, saranno coinvolte tutte le celle dell'area.

filterscope: determina come filterformula si estende all'area indicata. Questo argomento è obbligatorio se è stato specificato l'argomento filterformula. Sono ammessi i seguenti valori:

- "CELL": la formula indicata nell'argomento filterformula si espande una volta per ogni cella nell'area range.

- "ROW": la formula specificata nell'argomento filterformula si espande una volta per ogni riga nell'area range.

- "COLUMN": la formula specificata nell'argomento filterformula si espande una volta per ogni colonna nell'area range.

### Esempio:

##### In Basic

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

##### In Python

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

Per degli esempi su come usare gli argomenti filterformula e filterscope fare riferimento alla documentazione, disponibile sopra, del metodo ClearAll.

## ColorizeRange

Definisce i colori di primo piano e di sfondo di un intervallo di celle.

Le celle influenzate possono essere determinate con una formula di filtro e dal suo ambito.

### Sintassi:

svc.ColorizeRange(targetrange: str, opt foreground: int, opt background: int, opt filterformula: str, opt filterscope: str)

### Parametri:

targetrange: la cella o l'intervallo in formato stringa nel quale le celle devono essere (ri)colorate.

foreground: il colore di primo piano nel formato di output della funzione RGB(). Un valore negativo elimina il colore di primo piano.

background: il colore di sfondo nel formato di output della funzione RGB(). Un valore negativo elimina il colore di sfondo.

filterformula: una formula di Calc da applicare all'area indicata per determinare quali celle saranno coinvolte. La formula specificata deve restituire True o False. Se questo argomento non è specificato, saranno coinvolte tutte le celle dell'area.

filterscope: determina come filterformula si estende all'area indicata. Questo argomento è obbligatorio se è stato specificato l'argomento filterformula. Sono ammessi i seguenti valori:

- "CELL": la formula indicata nell'argomento filterformula si espande una volta per ogni cella nell'area range.

- "ROW": la formula specificata nell'argomento filterformula si espande una volta per ogni riga nell'area range.

- "COLUMN": la formula specificata nell'argomento filterformula si espande una volta per ogni colonna nell'area range.

### Esempio:

##### In Basic

            ' Colora di rosso le celle numeriche.
            doc.ColorizeRange("SheetX.A1:J30", background := RGB(255, 0, 0), filterformula := "=IsNumeric(A1), filterscope := "CELL")

##### In Python

            # Colora di rosso le celle numeriche.
            basic = CreateScriptService('basic')
            doc.ColorizeRange('SheetX.A1:J30', background = basic.RGB(255, 0, 0), filterformula = '=IsNumeric(A1)', filterscope = 'CELL')

## CompactLeft

Rimuove da uno specifico intervallo le colonne che corrispondono a un filtro espresso come formula di Calc. Il filtro viene applicato a ogni colonna per decidere se questa sarà rimossa o no.

La rimozione della colonna può essere limitata all'altezza dell'intervallo specificato oppure estendersi all'altezza dell'intero foglio, eliminando perciò intere colonne.

Questo metodo restituisce una stringa con l'indirizzo dell'intervallo di celle compattato. Se tutte le colonne sono state rimosse, allora viene restituita una stringa vuota.

Se è selezionato un intervallo di celle, la chiamata di questo metodo non avrà effetto sulla selezione.

### Sintassi:

svc.CompactLeft(range: str, wholecolumn: bool = False, opt filterformula: str): str

### Parametri:

range: l'area da cui saranno eliminate le colonne, in formato stringa.

wholecolumn: se questa opzione è impostata su True l'intera colonna sarà rimossa dal foglio. Il valore predefinito è False, che significa che l'altezza della colonna rimossa sarà limitata all'altezza dell'intervallo specificato.

filterformula: il filtro da applicare a ciascuna colonna per determinare se dev'essere eliminata o no. Il filtro è espresso come una formula di Calc da applicare alla prima colonna. Se la formula restituisce True per una colonna, questa sarà eliminata. Il filtro predefinito elimina tutte le colonne vuote.

Per esempio, supponendo che sia selezionato l'intervallo A1:J200 (altezza = 200), la formula predefinita è =(COUNTBLANK(A1:A200)=200). Questo significa che se tutte le 200 celle della prima colonna sono vuote (Colonna A), la colonna sarà eliminata. Da notare che la formula espressa fa riferimento solo alla prima colonna. Internamente il metodo CompactLeft generalizzerà questa formula per tutte le colonne rimanenti.

Le funzioni di Calc usate nell'argomento filterformula devono essere espresse usando il loro nome in inglese. Visitare la pagina Elenco delle funzioni di Calc del Wiki per un elenco completo delle funzioni di Calc in inglese.

### Esempio:

##### In Basic

        ' Elimina tutte le colonne vuote nell'intervallo G1:L10 del foglio Sheet1
        newrange = oDoc.CompactLeft("Foglio1.G1:L10")
        ' L'esempio seguente è simile, ma dal foglio viene eliminata l'intera colonna
        newrange = oDoc.CompactLeft("Foglio1.G1:L10", WholeColumn := True)
        ' Elimina tutte le colonne in cui la prima riga è contrassegnata con una "X"
        newrange = oDoc.CompactLeft("Foglio1.G1:L10", FilterFormula := "=(G1=""X"")")
        ' Elimina tutte le colonne in cui la somma dei valori della colonna è dispari
        newrange = oDoc.CompactLeft("Foglio1.G1:L10", FilterFormula := "=(MOD(SUM(G1:G10);2)=1)")

##### In Python

        newrange = myDoc.CompactLeft("Foglio1.G1:L10")
        newrange = myDoc.CompactLeft("Foglio1.G1:L10", wholecolumn = True)
        newrange = myDoc.CompactLeft("Foglio1.G1:L10", filterformula = '=(G1="X")')
        newrange = myDoc.CompactLeft("Foglio1.G1:L10", filterformula = '=(MOD(SUM(G1:G10);2)=1)')

## CompactUp

Elimina tutte le righe di un intervallo specificato che rispettano le condizioni di un filtro espresso come formula di Calc. Il filtro è applicato a ogni riga per decidere se questa sarà eliminata o no.

Le righe eliminate possono limitarsi alla larghezza dell'intervallo specificato o estendersi alla larghezza dell'intero foglio, eliminando quindi righe intere.

Questo metodo restituisce una stringa con l'indirizzo dell'intervallo compattato. Se vengono eliminate tutte le righe, sarà restituita una stringa vuota.

Se è selezionato un intervallo di celle, la chiamata di questo metodo non avrà effetto sulla selezione.

### Sintassi:

svc.CompactUp(range: str, wholerow: bool = False, opt filterformula: str): str

### Parametri:

range: l'area da cui saranno eliminate le righe, in formato stringa.

wholerow: se questa opzione è impostata a True l'intera riga sarà eliminata dal foglio. Il valore predefinito è False, che significa che le righe eliminate si limiteranno alla larghezza dell'intervallo specificato.

filterformula: il filtro da applicare a ogni riga per determinare se questa sarà eliminata o no. Il filtro è espresso come formula di Calc da applicare alla prima riga. Se la formula restituisce True per una riga, questa sarà eliminata. Il filtro predefinito elimina tutte le righe vuote.

Per esempio, supponendo che sia selezionato l'intervallo A1:J200 (larghezza = 10), la formula predefinita sarà =(COUNTBLANK(A1:J1)=10). Questo significa che se tutte le 10 celle della prima riga (Riga 1) sono vuote, allora la riga sarà eliminata. Da notare che la formula espressa fa riferimento solo alla prima riga. Internamente il metodo CompactUp generalizzerà questa formula per tutte le righe restanti.

Le funzioni di Calc usate nella formula specificata nell'argomento filterformula devono essere espresse usando il loro nome in inglese. Per un elenco completo delle funzioni di Calc in inglese visitare la pagina del Wiki Elenco delle funzioni di Calc.

### Esempio:

##### In Basic

        ' Elimina tutte le righe vuote nell'intervallo G1:L10 del foglio Sheet1
        newrange = oDoc.CompactUp("Foglio1.G1:L10")
        ' L'esempio seguente è simile, ma dal foglio viene eliminata l'intera riga
        newrange = oDoc.CompactUp("Foglio1.G1:L10", WholeRow := True)
        ' Elimina tutte le righe nelle quali la prima colonna è contrassegnata con una "X"
        newrange = oDoc.CompactUp("Foglio1.G1:L10", FilterFormula := "=(G1=""X"")")
        ' Elimina tutte le righe in cui la somma dei valori della riga è dispari
        newrange = oDoc.CompactUp("Foglio1.G1:L10", FilterFormula := "=(MOD(SUM(G1:L1);2)=1)")

##### In Python

        newrange = myDoc.CompactUp("Foglio1.G1:L10")
        newrange = myDoc.CompactUp("Foglio1.G1:L10", wholerow = True)
        newrange = myDoc.CompactUp("Foglio1.G1:L10", filterformula = '=(G1="X")')
        newrange = myDoc.CompactUp("Foglio1.G1:L10", filterformula = '=(MOD(SUM(G1:L1);2)=1)')

## 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 "SheetX" e la posiziona come ultimo foglio del documento corrente. Il nome del foglio risultante dalla copia è "SheetY".

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

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

          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 = ui.OpenDocument(r"C:\Documents\FileA.ods", hidden = True, readonly = True)
        docB = ui.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 "SheetX" dal file "mioFile.ods" e lo incolla come "SheetY" 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 = ui.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("SheetX.A1:F10", "SheetY.C5:J5")

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

## CreateChart

Crea un nuovo oggetto di tipo grafico che illustra i dati dell'intervallo specificato. L'oggetto di tipo grafico restituito può essere ulteriormente manipolato usando il servizio Chart.

### Sintassi:

svc.CreateChart(chartname: str, sheetname: str, range: str, columnheader: bool = False, rowheader: bool = False): obj

### Parametri:

chartname: il nome assegnato dall'utente al grafico da creare. Il nome deve essere univoco all'interno dello stesso foglio.

sheetname: il nome del foglio nel quale il grafico sarà posizionato.

range: l'intervallo da usare come sorgente dei dati per il grafico. L'intervallo può far riferimento a qualsiasi foglio del documento di Calc.

columnheader: se impostato su True, la riga più in alto dell'area è usata per le etichette delle categorie degli assi o della legenda (predefinito = False).

rowheader: se impostato su True, la colonna più a sinistra nell'intervallo è usata per le etichette delle categorie degli assi o della legenda (predefinito = False).

### Esempio:

L'esempio sottostante in Basic e Python crea un grafico usando i dati contenuti nell'intervallo "A1:B5" del foglio "Sheet1" e posiziona il grafico nel foglio "Sheet2".

##### In Basic

        Set oChart = oDoc.CreateChart("MyChart", "Sheet2", "Sheet1.A1:B5", RowHeader := True)
        oChart.ChartType = "Donut"

##### In Python

        chart = doc.CreateChart("MyChart", "Sheet2", "Sheet1.A1:B5", rowheader=True)
        chart.ChartType = "Donut"

Fare riferimento alle pagine della guida in linea relative al servizio Chart di ScriptForge per saperne di più su come manipolare ulteriormente gli oggetti di tipo grafico. È possibile modificarne le proprietà come il tipo di grafico, i titoli del grafico e degli assi e la posizione del grafico.

## CreatePivotTable

Crea una nuova tabella pivot con le proprietà definite dagli argomenti passati al metodo.

Deve essere fornito un nome per la tabella pivot. Se nel foglio di destinazione esiste già una tabella pivot con lo stesso nome, questa viene sostituita senza avvertimenti.

Questo metodo restituisce una stringa contenente l'intervallo in cui è stata posizionata la nuova tabella pivot.

### Sintassi:

svc.CreatePivotTable(pivottablename: str, sourcerange: str, targetcell: str, datafields: str[0..*], rowfields: str[0..*], columnfields: str[0..*], filterbutton: bool = true, rowtotals: bool = true, columntotals: bool = true): str

### Parametri:

pivottablename: il nome definito dall'utente per la nuova tabella pivot.

sourcerange: l'intervallo contenente i dati grezzi, in formato stringa. Si presume che la prima riga contenga i nomi dei campi usati dalla tabella pivot.

targetcell: la prima cella in alto a sinistra in cui sarà posizionata la nuova tabella pivot. Se è specificato un intervallo, viene presa in considerazione solamente la sua prima cella in alto a sinistra.

datafields: può essere sia una singola stringa, sia una matrice contenente le stringhe che definiscono i nomi dei campi e le funzioni da applicare. Se è specificata una matrice, deve rispettare la sintassi Array("FieldName[;Function]", ...).

Le funzioni consentite sono: Sum, Count, Average, Max, Min, Product, CountNums, StDev, StDevP, Var, VarP e Median. I nomi delle funzioni devono essere indicati in inglese. Quando tutti i valori sono numerici la funzione predefinita è Sum, altrimenti è Count.

rowfields: una singola stringa o una matrice con i nomi dei campi da usare per le righe della tabella pivot.

columnfields: una singola stringa o una matrice con i nomi dei campi da usare per le colonne della tabella pivot.

filterbutton: determina se sopra la tabella pivot sarà visualizzato un pulsante filtro (Predefinito = True).

rowtotals: specifica se alla tabella pivot sarà aggiunta una colonna separata per i totali (Predefinito = True).

columntotals: specifica se alla tabella pivot sarà aggiunta una riga separata per i totali (Predefinito True)

### Esempio:

##### In Basic

        Dim vData As Variant, oDoc As Object, ui As Object, sTable As String, sPivot As String
        Set ui = CreateScriptService("UI")
        Set oDoc = ui.CreateDocument("Calc")
        vData = Array(Array("Item", "State", "Team", "2002", "2003", "2004"), _
            Array("Books", "Michigan", "Jean", 14788, 30222, 23490), _
            Array("Candy", "Michigan", "Jean", 26388, 15641, 32849), _
            Array("Pens", "Michigan", "Jean", 16569, 32675, 25396), _
            Array("Books", "Michigan", "Volker", 21961, 21242, 29009), _
            Array("Candy", "Michigan", "Volker", 26142, 22407, 32841))
        sTable = oDoc.SetArray("A1", vData)
        sPivot = oDoc.CreatePivotTable("PT1", sTable, "H1", _
            Array("2002", "2003;count", "2004;average"), _ ' tre campi di dati
            "Item", _ ' una riga con un solo campo
            Array("State", "Team"), False) ' due colonne per i campi

##### In Python

        ui = CreateScriptService("UI")
        doc = ui.CreateDocument("Calc")
        vData = [["Item", "State", "Team", "2002", "2003", "2004"],
                 ["Books", "Michigan", "Jean", 14788, 30222, 23490],
                 ["Candy", "Michigan", "Jean", 26388, 15641, 32849],
                 ["Pens", "Michigan", "Jean", 16569, 32675, 25396)],
                 ["Books", "Michigan", "Volker", 21961, 21242, 29009],
                 ["Candy", "Michigan", "Volker", 26142, 22407, 32841]]
        sTable = doc.SetArray("A1", vData)
        sPivot = doc.CreatePivotTable("PT1", sTable, "H1",
                                      ["2002", "2003;count", "2004;average"],
                                      "Item",
                                      ["State", "Team"], False)

Per saperne di più sulle tabelle pivot in LibreOffice Calc, leggere la pagina Tabella pivot della guida in linea.

## DAvg, DCount, DMax, DMin and DSum

Applica le funzioni Media, Conta, Max, Min e Somma, rispettivamente, a tutte le celle che contengono valori numerici di un intervallo specificato, escludendo i valori delle righe filtrate e nascoste e delle colonne nascoste, lo stesso avviene per le funzioni della barra di stato.

### 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.

## DecorateFont

Specifica semplici proprietà del tipo di carattere da usare nell'intervallo di celle.

Le celle influenzate possono essere determinate con una formula di filtro e dal suo ambito.

Per applicare formattazioni più complesse del tipo di carattere, applicare le solite e numerose proprietà UNO disponibili nelle interfacce XCell o XCellRange.

### Sintassi:

svc.DecorateFont(targetrange: str, opt fontname: str, opt fontsize: int, opt decoration: str, opt filterformula: str, opt filterscope: str)

### Parametri:

targetrange: la cella o l'intervallo in formato stringa nel quale il tipo di carattere dev'essere riformattato.

fontname: il nome del tipo di carattere da usare. Il nome non viene controllato. Valore predefinito = nessuna modifica.

fontsize: le dimensioni del tipo di carattere in pixel. Valore predefinito = nessuna modifica.

decoration: una stringa che combina uno o più dei seguenti caratteri maiuscoli (altri caratteri vengono ignorati). Valore predefinito = nessuna modifica:

- B, U, I, S: Grassetto, Sottolineato, Corsivo, Barrato (Bold, Underline, Italic, Strikethrough)

filterformula: una formula di Calc da applicare all'area indicata per determinare quali celle saranno coinvolte. La formula specificata deve restituire True o False. Se questo argomento non è specificato, saranno coinvolte tutte le celle dell'area.

filterscope: determina come filterformula si estende all'area indicata. Questo argomento è obbligatorio se è stato specificato l'argomento filterformula. Sono ammessi i seguenti valori:

- "CELL": la formula indicata nell'argomento filterformula si espande una volta per ogni cella nell'area range.

- "ROW": la formula specificata nell'argomento filterformula si espande una volta per ogni riga nell'area range.

- "COLUMN": la formula specificata nell'argomento filterformula si espande una volta per ogni colonna nell'area range.

### Esempio:

##### In Basic

            ' Modifica le dimensioni del tipo di carattere e applica le proprietà grassetto e sottolineato alle celle numeriche.
            doc.DecorateFont("SheetX.A1:J30", fontsize := 15, decoration := "Bold,Underline", filterformula := "=IsNumeric(A1)", filterscope := "CELL")

##### In Python

            # Modifica le dimensioni del tipo di carattere e applica le proprietà grassetto e sottolineato alle celle numeriche.
            doc.DecorateFont('SheetX.A1:J30', fontsize = 15, decoration = 'Bold,Underline', filterformula = '=IsNumeric(A1)', filterscope = 'CELL')

## DefineName

Definisce un nuovo nome nel foglio elettronico a livello globale o del singolo foglio. Se il nome esiste già, viene sovrascritto senza avvisare. Dopo la sua creazione, il nuovo nome può essere usato nelle formule. Restituisce True se eseguito correttamente.

Usare la proprietà DefinedNames per esaminare i nomi degli intervalli già esistenti.

### Sintassi:

svc.DefineName(definedname: str, value: any, opt sheetname: str): boolean

### Parametri:

definedname: il nome da creare o modificare senza avvertimento. Da notare che possono coesistere delle omonimie, ma non nello stesso foglio o a livello globale del documento.

value - il nuovo nome come:

- un riferimento a un intervallo in formato stringa, spesso una singola cella

- un valore scalare in formato numero o stringa

- una formula che inizia con il segno "="

Quando Value è un intervallo, la cella in alto a sinistra viene impostata come cella di riferimento.

sheetname: l'ambito di applicazione del nome definito è quello del foglio specificato. L'abbreviazione "~" è accettata.

### Esempio:

##### In Basic

            doc.DefineName("NewName", Sheet := "Sheet3", Value := "H2")

##### In Python

            doc.DefineName('NewName', sheet = 'Sheet3', value = 'H2')

## ExportRangeToFile

Esporta l'intervallo specificato in formato immagine o in un file PDF.

Questo metodo restituisce True se il file di destinazione è stato salvato correttamente.

Le colonne o le righe nascoste nell'intervallo specificato non sono esportate nel file di destinazione.

### Sintassi:

svc.ExportRangeToFile(range: str, filename: str, imagetype: str = "pdf", overwrite: bool = False): bool

### Parametri:

range: il nome di un foglio o un intervallo di celle da esportare, espresso in formato stringa.

filename: il nome del file da salvare. Deve rispettare la notazione SF_FileSystem.FileNaming.

imagetype: identifica il tipo per il file di destinazione. I valori possibili sono "jpeg", "pdf" (predefinito) e "png".

overwrite: se impostato a True, il file di destinazione può essere sovrascritto (predefinito = False).

### Esempio:

##### In Basic

        ' Esporta l'intero foglio in un file PDF
        oDoc.ExportRangeToFile("SheetX", "C:\Temp\image.pdf")
        ' Esporta l'intervallo in un file PNG e sovrascrive il file di destinazione se esiste già
        oDoc.ExportRangeToFile("SheetX.A1:D10", "C:\Temp\image.png", "png", Overwrite := True)

##### In Python

        doc.ExportRangeToFile("SheetX", r"C:\Temp\image.pdf")
        doc.ExportRangeToFile("SheetX.A1:D10", r"C:\Temp\image.png", "png", overwrite = True)

## FormatRange

Applica un determinato formato numerico a una cella o a un intervallo di celle.

Le celle influenzate possono essere determinate con una formula di filtro e dal suo ambito.

### Sintassi:

svc.FormatRange(targetrange: str, numberformat: str, opt locale: str, opt filterformula: str, opt filterscope: str)

### Parametri:

targetrange: la cella o l'intervallo in formato stringa a cui applicare la formattazione.

numberformat: il formato da applicare, passato come stringa.

locale: un combinazione li-PA (lingua-PAESE; es. it-IT per italiano-ITALIA) che indica le impostazioni locali da usare. Le impostazioni locali predefinite si ottengono dal risultato della funzione platform.FormatLocale.

filterformula: una formula di Calc da applicare all'area indicata per determinare quali celle saranno coinvolte. La formula specificata deve restituire True o False. Se questo argomento non è specificato, saranno coinvolte tutte le celle dell'area.

filterscope: determina come filterformula si estende all'area indicata. Questo argomento è obbligatorio se è stato specificato l'argomento filterformula. Sono ammessi i seguenti valori:

- "CELL": la formula indicata nell'argomento filterformula si espande una volta per ogni cella nell'area range.

- "ROW": la formula specificata nell'argomento filterformula si espande una volta per ogni riga nell'area range.

- "COLUMN": la formula specificata nell'argomento filterformula si espande una volta per ogni colonna nell'area range.

### Esempio:

##### In Basic

            ' Formatta solo le celle che contengono un valore numerico.
            doc.FormatRange("SheetX.A1:J30", "0,00E+00", filterformula := "=IsNumeric(A1)", filterscope := "CELL")

##### In Python

            # Formatta solo le celle che contengono un valore numerico.
            doc.FormatRange('SheetX.A1:J30', '0,00E+00', filterformula = '=IsNumeric(A1)', filterscope = 'CELL')

## 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("Sheet1")
        Set FormA = oDoc.Forms("Sheet1", "Form_A")

##### In Python

        form_names = doc.Forms("Sheet1")
        form_A = doc.Forms("Sheet1", "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 ... 16384.

### Esempio:

##### In Basic

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

        MsgBox oDoc.GetColumnName(3)

##### In Python

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

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

## GetFormula

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

I nomi delle funzioni di Calc usate nelle formule restituite sono espressi in inglese. Per un elenco completo delle funzioni di Calc in inglese visitare la pagina del Wiki Elenco delle funzioni di Calc.

### 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, consultare la pagina della guida sulle Opzioni dei filtri.

## 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 impostato su 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]")

### ImportStylesFromFile

Questo metodo carica, da un file chiuso, tutti gli stili che appartengono a una o più famiglie di stili, importandoli nel documento corrente. Quest'ultimo deve essere un documento di Calc o di Writer.

Vengono sempre importati assieme:

- gli stili di paragrafo (ParagraphStyles) e di carattere (CharacterStyles)

- gli stili di elenco numerato (NumberingStyles) e di elenco puntato (ListStyles)

Restituisce True se gli stili sono stati importati correttamente.

### Sintassi:

svc.ImportStylesFromFile(filename: str, families: str[1..*], overwrite = False): bool

### Parametri:

filename: il file da cui caricare gli stili in notazione FileSystem. Si presuppone che il file sia dello stesso tipo del documento corrente.

families: una delle famiglie di stili presenti nel documento corrente, in formato stringa che distingue tra lettere minuscole e maiuscole o una matrice di stringhe di questo tipo. Lasciare vuoto questo argomento per importare tutte le famiglie.

overwrite: se impostato a True, gli stili correnti possono essere sovrascritti (il valore predefinito è False).

### Esempio:

##### In Basic

        oDoc.ImportStylesFromFile("C:\User\Documents\myFile.ods", "ParagraphStyles", True)

##### In Python

        doc.ImportStylesFromFile('C:\User\Documents\myFile.ods', ("ParagraphStyles",), False)

## 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 "SheetX" e lo posiziona prima del "SheetY":

##### In Basic

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

##### In Python

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

## Intersect

Restituisce la stringa che rappresenta l'intersezione tra i due intervalli di input, o una stringa di lunghezza zero se l'intersezione è vuota.

### Sintassi:

svc.Intersect(range1:str, range2: str): str

### Parametri:

intervallo1: la stringa con l'indirizzo dell'intervallo 1.

intervallo2: la stringa con l'indirizzo dell'intervallo 2.

### Esempio:

L'esempio seguente trova l'intersezione tra due intervalli e restituisce l'intervallo in comune tra loro:

##### In Basic

        Dim commonrange As String
        commonrange = oDoc.Intersect("A1:D8", "C3:F4")
        Print commonrange ' mostra "$Sheet1.$C$3:$D$4"

##### In Python

        common_range = myDoc.Intersect("A1:D8", "C3:F4")
        print(common_range) # restituisce '$Sheet1.$C$3:$D$4' nella shell di Python

## 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 "SheetX" e lo posiziona prima di "SheetY":

##### 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)
        'SheetX.$C$3 (A1 spostato in basso di due righe e due colonne)
        oDoc.Offset("A1", 2, 2, 5, 6)
        'SheetX.$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)

## OpenRangeSelector

Apre una finestra di dialogo non modale, che potete usare per selezionare un intervallo all'interno del documento, e restituisce una stringa contenente l'area selezionata.

Questo metodo apre la stessa finestra di dialogo usata da LibreOffice quando viene premuto il pulsante Riduci. Per esempio, la finestra di dialogo Strumenti - Ricerca valore destinazione ha un pulsante Riduci alla destra del campo Cella formula.

Questo metodo non modifica la seleziona corrente.

### Sintassi:

svc.OpenRangeSelector(opt title: str, opt selection: str, singlecell: bool = False, closeafterselect: bool = True): str

### Parametri:

title: il titolo della finestra di dialogo, in formato stringa.

selection: l'intervallo opzionale, che verrà inizialmente selezionato al momento della visualizzazione della finestra di dialogo.

singlecell: se impostato su True (predefinito) è ammessa solamente la selezione di una singola cella. Se è False è permessa la selezione di un intervallo.

closeafterselect: se impostato su True (predefinito), la finestra di dialogo si chiude immediatamente dopo aver eseguito la selezione. Se è False, la selezione sarà modificabile tante volte quante se ne ha la necessità, quindi si dovrà chiudere manualmente la finestra.

### Esempio:

##### In Basic

        Dim sRange as String
        sRange = oDoc.OpenRangeSelector(Title := "Select a range")

##### In Python

        sRange = myDoc.OpenRangeSelector(title = "Select a range")

## Printf

Restituisce la stringa inserita dopo aver sostituito i caratteri segnaposto con i rispettivi valori all'interno dell'area precisata.

Questo metodo non modifica la seleziona corrente.

Potete usare questo metodo per estrarre velocemente delle parti specifiche di un'area con nome, come il nome del foglio o la colonna e la riga della prima cella, e usarle per comporre gli indirizzi di nuovi intervalli.

### Sintassi:

svc.Printf(inputstr: str, range: str, tokencharacter: str = "%"): str

### Parametri:

inputstr: la stringa contenente i token che saranno sostituiti dai valori corrispondenti all'interno di range.

range: il nome di un intervallo RangeName da cui saranno estratti i valori. Se contiene il nome di un foglio, il foglio deve esistere.

tokencharacter: i caratteri usati per identificare i token. Il carattere predefinito per i token è "%". Sono ammessi i seguenti token:

- %S - il nome del foglio che contiene l'area, comprensivo delle virgolette semplici se necessario.

- %R1 - il numero di riga della cella superiore sinistra all'interno dell'area.

- %C1 - la lettera della colonna della cella superiore sinistra all'interno dell'area.

- %R2 - il numero di riga della cella inferiore destra all'interno dell'area.

- %C2 - la lettera della colonna della cella inferiore destra all'interno dell'area.

### Esempio:

##### In Basic

L'esempio seguente estrae tutti gli elementi dell'area RangeName definita in sRange e li usa per comporre un messaggio.

        Dim sRange as String, sInputStr as String
        sRange = "Sheet1.A1:E10"
        sInputStr = "Sheet name: %S" & Chr(10) & _
                    "First row: %R1" & Chr(10) & _
                    "First column %C1" & Chr(10) & _
                    "Last row %R2" & Chr(10) & _
                    "Last column %C2"
        MsgBox oDoc.Printf(sInputStr, sRange)

Potete combinare il metodo Printf con SetFormula per creare formule su più celle. Per esempio, prendete in considerazione una tabella di valori numerici nell'intervallo "A1:E10", dai quali creare delle formule che sommino i valori di ogni riga posizionando i risultati nell'area "F1:F10":

        Dim sFormula as String, sRange as String
        sRange = "A1:E10"
        ' Notate l'uso del carattere "$"
        sFormula = "=SUM($%C1%R1:$%C2%R1)"
        oDoc.SetFormula("F1:F10", oDoc.Printf(sFormula, sRange))

##### In Python

        sRange = "Sheet1.A1:E10"
        sInputStr = "Sheet name: %S\n" \
                    "First row: %R1\n" \
                    "First column %C1\n" \
                    "Last row %R2\n" \
                    "Last column %C2"
        bas = CreateScriptService("Basic")
        bas.MsgBox(myDoc.Printf(sInputStr, sRange))

        sRange = "A1:E10
        sFormula = "=SUM($%C1%R1:$%C2%R1)"
        myDoc.SetFormula("F1:F10", myDoc.Printf(sFormula, sRange))

## PrintOut

Questo metodo invia i contenuti del foglio indicato alla stampante predefinita o alla stampante precisata dal metodo SetPrinter del servizio Document.

Restituisce True se il foglio è stato stampato correttamente.

### Sintassi:

svc.PrintOut(opt sheetname: str, pages: str = "", copies: num = 1): bool

### Parametri:

sheetname: il foglio da stampare, l'impostazione predefinita è il foglio attivo.

pages: le pagine da stampare in formato stringa, come nell'interfaccia utente. Esempio "1-4;10;15-18". L'impostazione predefinita è tutte le pagine.

copies: il numero di copie. Il valore predefinito è 1.

### Esempio:

##### In Basic

        If oDoc.PrintOut("SheetX", "1-4;10;15-18", Copies := 2) Then
            ' ...
        End If

##### In Python

        if doc.PrintOut('SheetX', copies=3, pages='45-88'):
            # ...

## RemoveDuplicates

Elimina le righe duplicate da un intervallo specificato. Il confronto per determinare se una determinata riga è duplicata è fatto sulla base di un sottoinsieme di colonne dell'intervallo.

Questo metodo restituisce una stringa che contiene l'intervallo risultante.

La rimozione delle righe duplicate è fatta partendo dalla prima riga dell'intervallo e spostandosi verso il basso, questo significa che se due o più righe sono duplicate sarà conservata solo la prima.

### Sintassi:

svc.RemoveDuplicates(range: str, opt columns: int[0..*], header: bool = False, casesensitive: bool = False, mode: str = "COMPACT"): str

### Parametri:

range: l'area da cui saranno rimossi i duplicati, in formato stringa.

columns: una matrice contenente i numeri che indicano quali colonne considerare per determinare se una riga è un duplicato o no. Se questo argomento è lasciato vuoto, sarà usata solo la prima colonna. Gli elementi in questa matrice devono essere compresi tra 1 e la larghezza dell'intervallo.

header: specifica se la prima riga contiene intestazioni o no (predefinito = False).

casesensitive: specifica se il confronto delle stringhe fa distinzione tra minuscole e maiuscole (predefinito = False).

mode: specifica cosa fare delle righe duplicate. Se mode = "CLEAR" i duplicati sono semplicemente eliminati dal foglio lasciando vuote le celle. Se mode = "COMPACT" i duplicati sono eliminati e le righe vuote vengono compattate verso l'alto (predefinito = "COMPACT").

### Esempio:

##### In Basic

        ' Elimina le righe duplicate se i valori nella colonna A sono duplicati
        ' Notare che tutti gli argomenti opzionali usano il loro valore predefinito
        oDoc.RemoveDuplicates("A1:B10")
        ' Elimina le righe duplicate considerando che la prima riga contiene delle intestazioni
        ' Le colonne A e B sono usate per determinare se una riga è un duplicato
        ' Le celle che contengono valori duplicati sono lasciate vuote
        oDoc.RemoveDuplicates("A1:D10", columns := Array(1, 2), header := True, mode := "CLEAR")

##### In Python

        myDoc.RemoveDuplicates("A1:B10")
        myDoc.RemoveDuplicates("A1:D10", columns = (1, 2), header = True, mode = "CLEAR")

## 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.

## 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, opt filterformula: str, opt filterscope: str): str

### Parametri:

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

style: il nome dello stile di cella da applicare.

filterformula: una formula di Calc da applicare all'area indicata per determinare quali celle saranno coinvolte. La formula specificata deve restituire True o False. Se questo argomento non è specificato, saranno coinvolte tutte le celle dell'area.

filterscope: determina come filterformula si estende all'area indicata. Questo argomento è obbligatorio se è stato specificato l'argomento filterformula. Sono ammessi i seguenti valori:

- "CELL": la formula indicata nell'argomento filterformula si espande una volta per ogni cella nell'area range.

- "ROW": la formula specificata nell'argomento filterformula si espande una volta per ogni riga nell'area range.

- "COLUMN": la formula specificata nell'argomento filterformula si espande una volta per ogni colonna nell'area range.

### 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")

Per degli esempi su come usare gli argomenti filterformula e filterscope fare riferimento alla documentazione, disponibile sopra, del metodo ClearAll.

## 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.

Le funzioni di Calc usate nell'argomento formula devono essere espresse usando il loro nome in inglese. Per un elenco completo delle funzioni di Calc in inglese visitare la pagina del Wiki Elenco delle funzioni di Calc.

### 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")

## 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)

## ShiftDown

Sposta in basso l'area di celle indicata inserendo delle righe vuote. La selezione corrente non varia.

A seconda del valore dell'argomento wholerow le righe inserite possono estendersi alla larghezza dell'intervallo specificato o a tutte le colonne della riga.

Questo metodo restituisce una stringa che rappresenta la nuova posizione dell'area di partenza.

Se l'area spostata va oltre i margini del foglio, non succede nulla.

### Sintassi:

svc.ShiftDown(range: str, wholerow: bool = False, opt rows: int): str

### Parametri:

range: l'area sopra cui saranno inserite le righe, in formato stringa.

wholerow: se è impostato su False (predefinito), la larghezza delle righe inserite sarà la stessa dell'area range specificata. Altrimenti, le righe inserite si estenderanno a tutte le colonne del foglio.

rows: il numero di righe da inserire. Il valore predefinito è pari all'altezza dell'area range di partenza. Il numero di righe deve essere positivo.

### Esempio:

##### In Basic

        ' Sposta in basso di una riga l'area "A3:D3"; ha effetto solo sulle colonne dalla A alla D
        oDoc.ShiftDown("A3:D3")
        ' La riga inserita si estende a tutte le colonne del foglio
        oDoc.ShiftDown("A3:D3", WholeRow := True)
        ' Sposta in basso di cinque righe l'area "A3:D3"
        oDoc.ShiftDown("A3:D3", Rows := 5)
        ' Sposta in basso di due righe l'area "A3:D10" e mostra la nuova posizione dell'area di partenza
        Dim sNewRange as String
        sNewRange = oDoc.ShiftDown("A3:D10", Rows := 2)
        MsgBox sNewRange   ' $Sheet1.$A$5:$D$12

##### In Python

        myDoc.ShiftDown("A3:D3")
        myDoc.ShiftDown("A3:D3", wholerow = True)
        myDoc.ShiftDown("A3:D3", rows = 5)
        sNewRange = myDoc.ShiftDown("A3:D10", rows = 2)
        bas = CreateScriptService("Basic")
        bas.MsgBox(sNewRange)

## ShiftLeft

Elimina la prima colonna a sinistra dell'intervallo specificato e sposta a sinistra tutte le celle che si trovano a destra dell'intervallo interessato. Non ha effetto sulla selezione corrente.

A seconda del valore dell'argomento wholecolumn le colonne eliminate possono estendersi all'altezza dell'intervallo specificato o a tutte le righe della colonna.

Questo metodo restituisce una stringa che rappresenta la posizione della parte che rimane dell'intervallo di partenza. Se sono state eliminate tutte le celle dell'intervallo di partenza, viene restituita una stringa vuota.

### Sintassi:

svc.ShiftLeft(range: str, wholecolumn: bool = False, opt columns: int): str

### Parametri:

range: l'area da cui saranno eliminate le celle, in formato stringa.

wholecolumn: se è impostato su False (predefinito), l'altezza delle colonne eliminate sarà la stessa dell'area range specificata. Altrimenti, le colonne eliminate si estenderanno a tutte le righe del foglio.

columns: il numero di colonne da eliminare dall'area range specificata. Il valore predefinito è pari alla larghezza dell'area range di partenza, che è anche il valore massimo di questo argomento.

### Esempio:

##### In Basic

        ' Elimina l'area "B3:B6"; sposta a sinistra tutte le celle che si trovano alla sua destra
        oDoc.ShiftLeft("B3:B6")
        ' Elimina la prima colonna dell'intervallo "A3:D6"
        oDoc.ShiftLeft("A3:D6", Columns := 1)
        ' Le colonne eliminate (dalla A alla D) si estendono a tutte le righe del foglio
        oDoc.ShiftLeft("A3:D6", WholeColumn := True)

##### In Python

        myDoc.ShiftLeft("B3:B6")
        myDoc.ShiftLeft("A3:D6", Columns = 1)
        myDoc.ShiftLeft("A3:D6", WholeColumn = True)

## ShiftUp

Elimina le righe più in alto dell'area specificata e sposta in alto tutte le celle al di sotto dell'area interessata. Non ha effetto sulla selezione corrente.

A seconda del valore dell'argomento wholerow le righe eliminate possono estendersi alla larghezza dell'intervallo specificato o a tutte le colonne della riga.

Questo metodo restituisce una stringa che rappresenta la posizione della parte che rimane dell'intervallo di partenza. Se sono state eliminate tutte le celle dell'intervallo di partenza, viene restituita una stringa vuota.

### Sintassi:

svc.ShiftUp(range: str, wholerow: bool = False, opt rows: int): str

### Parametri:

range: l'area da cui saranno eliminate le celle, in formato stringa.

wholerow: se è impostato su False (predefinito), la larghezza delle righe eliminate sarà quella dell'intervallo range specificato. In caso contrario, la riga eliminata si estenderà a tutte le colonne del foglio.

rows: il numero di righe da eliminare dall'intervallo range specificato. Il valore predefinito è pari all'altezza dell'intervallo range di partenza, che rappresenta anche il valore massimo di questo argomento.

### Esempio:

##### In Basic

        ' Elimina l'area "A3:D3" e sposta tutte le celle sottostanti in alto di una riga
        oDoc.ShiftUp("A3:D3")
        ' Elimina la prima riga dell'area "A3:D6"
        oDoc.ShiftUp("A3:D6", Rows := 1)
        ' Le righe eliminate si estendono a tutte le colonne del foglio
        oDoc.ShiftUp("A3:D6", WholeRow := True)

##### In Python

        myDoc.ShiftUp("A3:D3")
        myDoc.ShiftUp("A3:D6", rows = 1)
        myDoc.ShiftUp("A3:D6", wholerow = True)

## ShiftRight

Sposta a destra l'area di celle indicata inserendo delle colonne vuote. Non ha effetto sulla selezione corrente.

A seconda del valore dell'argomento wholecolumn le colonne inserite possono estendersi all'altezza dell'intervallo specificato o a tutte le righe della colonna.

Questo metodo restituisce una stringa che rappresenta la nuova posizione dell'area di partenza.

Se l'area spostata va oltre i margini del foglio, non succede nulla.

### Sintassi:

svc.ShiftRight(range: str, wholecolumn: bool = False, opt columns: int): str

### Parametri:

range: l'area alla cui sinistra saranno inserite le colonne vuote, in formato stringa.

wholecolumn: se è impostato su False (predefinito), l'altezza delle colonne inserite sarà la stessa dell'intervallo range specificato. In caso contrario, le colonne inserite si estenderanno a tutte le righe del foglio.

columns: il numero di colonne da inserire. Il valore predefinito è pari alla larghezza dell'intervallo range di partenza.

### Esempio:

##### In Basic

        ' Sposta l'area "A3:A6" a destra di una colonna; ha effetto solo sulle righe dalla 3 alla 6
        oDoc.ShiftRight("A3:A6")
        ' Sposta l'area "A3:A6" a destra di cinque colonne
        oDoc.ShiftRight("A3:A6", Columns := 5)
        ' La colonna inserita si estende a tutte le righe del foglio
        oDoc.ShiftRight("A3:A6", WholeColumn := True)

##### In Python

        myDoc.ShiftRight("A3:A6")
        myDoc.ShiftRight("A3:A6", columns = 5)
        myDoc.ShiftRight("A3:A6", wholecolumn = True)

## SortRange

Ordina l'intervallo specificato in base a qualsiasi numero di colonne/righe. Il tipo di ordinamento può variare per ogni colonna/riga. Se il numero di chiavi di ordinamento è > 3 l'intervallo viene ordinato più volte, a gruppi di 3 chiavi, a partire dall'ultima. Restituisce una stringa che rappresenta l'intervallo di celle modificato. Le dimensioni dell'area modificata sono determinate interamente dalle dimensioni dell'area di origine.

### 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.

sortorder: uno scalare o una matrice di stringhe che contiene i valori "ASC" (ascendente), "DESC" (discendente). 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: se impostato su 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 o negli script in Python.

Argomenti correlati

Servizio SFDocuments.Chart

Servizio SFDocuments.Document

Servizio ScriptForge.UI

Sostienici!