SFDocuments.Calc-tjeneste

Innhold
Innholdsliste 🔎︎

# SFDocuments.Calc tjeneste

Det delte biblioteket SFDocuments gir en rekke metoder og egenskaper for å forenkle administrasjon og håndtering av LibreOffice-dokumenter.

Tjenesten SFDocuments.Calc er en underklasse av SFDocuments.Document tjeneste. Alle metoder og egenskaper definert for Dokument-tjenesten kan også nås ved å bruke en Calc-tjenesteforekomst.

Tjenesten Calc er fokusert på:

- Håndtering av ark i et Calc-dokument (kopiere, sette inn, flytte osv.)

- Utveksling av data mellom grunnleggende datastrukturer og Calc-områder

- Kopiering og import av enorme mengder data

Denne hjelpesiden beskriver metoder og egenskaper som bare gjelder for Calc-dokumenter.

## Tjenestepåkallelse

Før du bruker Calc-tjenesten, må ScriptForge-biblioteket lastes eller importeres:

• Grunnleggende makroer krever å laste ScriptForge-biblioteket ved hjelp av følgende setning:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
• Python-skript krever import fra scriptforge-modulen:
fra scriptforge import CreateScriptService

Tjenesten Calc er nært knyttet til UI-tjenesten til ScriptForge-biblioteket. Nedenfor er noen eksempler på hvordan Calc-tjenesten kan påkalles.

##### I Basic

Kodesnutten nedenfor oppretter en Calc-tjenesteforekomst som tilsvarer det aktive Calc-dokumentet.

        Set oDoc = CreateScriptService("Calc")

En annen måte å opprette en forekomst av Calc-tjenesten på er å bruke UI-tjenesten. I følgende eksempel opprettes et nytt Calc-dokument og oDoc er en Calc-tjenesteforekomst:

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

Eller ved å bruke OpenDocument-metoden fra UI-tjenesten:

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

Det er også mulig å instansiere Calc-tjenesten ved å bruke CreateScriptService-metoden:

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

I eksemplet ovenfor er "MyFile.ods" navnet på et åpent dokumentvindu. Hvis dette argumentet ikke er oppgitt, vurderes det aktive vinduet.

Det anbefales å frigjøre ressurser etter bruk:

        Set oDoc = oDoc.Dispose()

Men hvis dokumentet ble lukket med CloseDocument-metoden, blir det unødvendig å frigjøre ressurser ved å bruke kommandoen beskrevet ovenfor.

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

Bruken av prefikset "SFDocuments." mens du anroper tjenesten er valgfritt.

## Definisjoner

Mange metoder krever et "Ark" eller et "Område" som argument. Enkeltceller betraktes som et spesialtilfelle av et Område.

Begge kan uttrykkes enten som en streng eller som en referanse (= objekt) avhengig av situasjonen:

- Innenfor en spesifikk Calc forekomst er ark og områder gitt som strenger som "Ark1" og "D2:F6".

- I tillegg returnerer egenskapene .Ark og .Område en referanse som kan brukes som argument for en metode kalt fra en annen forekomst av en Calc tjeneste.

### Eksempel:

Eksemplet nedenfor kopierer data fra dokument A (åpnet som skrivebeskyttet og skjult) til dokument B.

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

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

Enten arknavnet som en streng eller et objekt produsert av egenskapen .Ark.

Snarveien "~" (tilde) representerer gjeldende ark.

### RangeName

Enten en streng som angir et sett med sammenhengende celler plassert i et ark av gjeldende forekomst eller et objekt produsert av egenskapen .Område.

Snarveien "~" (tilde) representerer gjeldende utvalg eller det første valgte området hvis flere områder er valgt.

Snarveien "*" representerer alle brukte celler.

Arknavnet er valgfritt når du definerer et område. Hvis det ikke er oppgitt noe arknavn, brukes det aktive arket. Omkringliggende enkeltanførselstegn og $-tegn er tillatt, men ignoreres.

When specifying a SheetName as a string, the use of single quotes to enclose the sheet name are required if the name contains blank spaces " " or periods ".".

The examples below illustrate in which cases the use of single quotes is mandatory:

          ' The use of single quotes is optional
          oDoc.clearAll("SheetA.A1:B10")
          oDoc.clearAll("'SheetA'.A1:B10")
          ' The use of single quotes is required
          oDoc.clearAll("'Sheet.A'.A1:B10")

Bortsett fra egenskapen GjeldendeUtvalg, vurderer tjenesten Calc bare enkeltområder med celler.

Eksempler på gyldige områder
1) $'SheetX'.D2 2) $D$2 | En enkelt celle
1) $'SheetX'.D2:F6 2) D2:D10 | Enkelt område med flere celler
$'SheetX'.* | Alle brukte celler i det aktuelle arket
1) $'SheetX'.A:A (column A) 2) 3:5 (rows 3 to 5) | Alle celler i sammenhengende kolonner eller rader opp til den sist brukte cellen
mittOmråde | Et område kalt "mittOmråde" på regnearknivå
1) ~.someRange 2) ArkX.someRange | Et områdenavn på arknivå
myDoc.Range("SheetX.D2:F6") | Et område innenfor arket SheetX i filen knyttet til myDoc Calc-forekomsten
~.~ eller ~ | Det gjeldende utvalget i det aktive arket

## Egenskaper

Alle egenskapene som er generiske for ethvert dokument er implisitt også gjeldende for Calc-dokumenter. For mer informasjon, les hjelpesiden for dokumenttjeneste.

Egenskapene som er spesifikt tilgjengelige for Calc-dokumenter er:

Navn | Skrivebeskyttet | Argument | Returtype | Beskrivelse
--- | --- | --- | --- | ---
CurrentSelection | Nei | Ingen | Strenger eller en rekke strenger | Det enkelt valgte området som en streng eller listen over valgte områder som en matrise.
FirstCell | Ja | Arknavn eller områdenavn som streng | String | Returnerer den første brukte cellen i et gitt område eller ark.
FirstColumn | Ja | Arknavn eller områdenavn som streng | Long | Returnerer kolonnenummeret lengst til venstre i et gitt område eller ark.
FirstRow | Ja | Arknavn eller områdenavn som streng | Long | Returnerer det øverste radnummeret i et gitt område eller ark.
Height | Ja | Områdenavn som streng | Long | Antall rader (>= 1) i det gitte området.
LastCell | Ja | Arknavn eller områdenavn som streng | String | Returnerer den sist brukte cellen i et gitt område eller ark.
LastColumn | Ja | Arknavn eller områdenavn som streng | Long | Den sist brukte kolonnen i et gitt område eller ark.
LastRow | Ja | Arknavn eller områdenavn som streng | Long | Den sist brukte raden i et gitt område eller ark.
Range | Ja | Områdenavn som streng | Object | En områdereferanse som kan brukes som argument for metoder som Kopier til område.
Region | Ja | Områdenavn som streng | String | Returnerer adressen til det minste området som inneholder det angitte området, slik at området er omgitt av tomme celler eller arkkanter. Dette tilsvarer å bruke Command + *Ctrl + * snarveien til det angitte området.
Sheet | Ja | Arknavn som streng | Object | En arkreferanse som kan brukes som argument for metoder som Kopier ark.
SheetName | Yes | RangeName As String | String | Returns the sheet name of a given range address.
Sheets | Ja | Ingen | Matrise med strenger | Listen med navn på alle eksisterende ark.
Width | Ja | Områdenavn som streng | Long | Antall kolonner (>= 1) i det gitte området.
XCellRange | Ja | Områdenavn som streng | Object | Et com.sun.star.Table.XCellRange UNO-objekt.
XSheetCellCursor | Ja | Områdenavn som streng | Object | Et com.sun.star.sheet.XSheetCellCursor UNO-objekt. Etter å ha flyttet markøren, kan den resulterende områdeadressen nås gjennom AbsoluteName UNO-egenskapen til markørobjektet, som returnerer en strengverdi som kan brukes som argument for egenskaper og metoder for Calc-tjenesten.
XSpreadsheet | Ja | Arknavn som streng | Object | Et com.sun.star.sheet.XSpreadsheet UNO-objekt.

Besøk nettstedet til LibreOffice API Dokumentasjonen for å lære mer om XCellRange, XSheetCellCursor og XSpreadsheet UNO-objekter.

## Metoder

Liste over metoder i Calc-tjenesten
A1Style Activate Charts ClearAll ClearFormats ClearValues CompactLeft CompactUp CopySheet CopySheetFromFile CopyToCell CopyToRange CreateChart CreatePivotTable DAvg | DCount DMax DMin DSum ExportRangeToFile Forms GetColumnName GetFormula GetValue ImportFromCSVFile ImportFromDatabase InsertSheet MoveRange MoveSheet Offset | OpenRangeSelector PrintOut Printf RemoveSheet RenameSheet SetArray SetValue SetCellStyle SetFormula ShiftDown ShiftLeft ShiftRight ShiftUp SortRange

## A1Style

Returnerer en områdeadresse som en streng basert på ark koordinater, dvs. rad- og kolonnenummer.

Hvis bare et par koordinater er gitt, returneres en adresse til en enkelt celle. Ytterligere argumenter kan spesifisere cellen nederst til høyre i et rektangulært område.

### Syntaks:

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

### Parametre:

rad1, kolonne1: Spesifiser rad- og kolonnenumrene til cellen øverst til venstre i området som skal vurderes. Rad- og kolonnenummer starter på 1.

rad2, kolonne2: Spesifiser rad- og kolonnenumrene til cellen nederst til høyre i området som skal vurderes. Hvis disse argumentene ikke er oppgitt, eller hvis verdier som er mindre enn rad1 og kolonne1 er gitt, er adressen til enkeltcelleområdet representert av rad1 og kolonne1 som returneres.

arknavn: Navnet på arket som skal legges til den returnerte områdeadressen. Arket må eksistere. Standardverdien er "~" som tilsvarer det aktive arket.

### Eksempel:

Eksemplene nedenfor i Basic og Python anser at "Ark1" er det aktive arket.

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

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

Metoden A1Style kan kombineres med alle de mange egenskapene og metodene til Calc-tjenesten som krever et område som argument, for eksempel GetValue, GetFormula, ClearAll osv.

## Activate

Hvis argumentet arknavn er oppgitt, aktiveres det gitte arket og det blir det valgte arket. Hvis argumentet er fraværende, aktiveres dokumentvinduet.

### Syntaks:

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

### Parametre:

arknavn: Navnet på arket som skal aktiveres i dokumentet. Standardverdien er en tom streng, noe som betyr at dokumentvinduet vil aktiveres uten å endre det aktive arket.

### Eksempel:

Eksemplet aktiverer arket kalt "Ark4" i det aktive dokumentet.

##### I Basic

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

##### I Python

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

Aktivering av et ark gir mening bare hvis det utføres på et Calc-dokument. For å være sikker på at du har et Calc-dokument for hånden kan du bruke egenskapen isCalc til dokumentobjektet, som returnerer Sann hvis det er et Calc-dokument og Usann ellers.

## Charts

Returnerer enten listen med navnene på alle kartobjekter i et gitt ark eller en enkelt Diagram tjenesteforekomst.

- If only sheetname is specified, a zero-based array of strings containing the names of all charts is returned.

- Hvis et diagramnavn er oppgitt, returneres et enkelt objekt som tilsvarer det ønskede diagrammet. Det angitte diagrammet må eksistere.

### Syntaks:

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

### Parametre:

arknavn: Navnet på arket som listen over diagrammer skal hentes fra eller hvor det angitte diagrammet er plassert.

kartnavn: Det brukerdefinerte navnet på diagramobjektet som skal returneres. Hvis diagrammet ikke har et brukerdefinert navn, kan det interne objektnavnet brukes. Hvis dette argumentet er fraværende, returneres listen over diagramnavn i det angitte arket.

Bruk sidefeltet Navigator for å sjekke navnene som er tildelt diagrammer under kategorien OLE-objekter.

### Eksempel:

##### I Basic

Eksemplet nedenfor viser antall kartobjekter i "Ark1".

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

Følgende eksempel gir tilgang til diagrammet kalt "MyChart" i "Ark1" og skriver ut typen.

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

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

Sletter alt innhold og formater for det gitte området.

### Syntaks:

svc.ClearAll(range: str)

### Parametre:

område: Området som skal slettes, som en streng.

### Eksempel:

##### I Basic

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

##### I Python

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

## ClearFormats

Fjerner formatene og stilene i det gitte området.

### Syntaks:

svc.ClearFormats(range: str)

### Parametre:

område: Området hvis formater og stiler skal slettes, som en streng.

### Eksempel:

##### I Basic

          oDoc.ClearFormats("SheetX.*")

##### I Python

        myDoc.ClearFormats("SheetX.*")

## ClearValues

Sletter verdiene og formlene i det gitte området.

### Syntaks:

svc.ClearValues(range: str)

### Parametre:

område: Området hvis verdier og formler skal slettes, som en streng.

### Eksempel:

##### I Basic

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

##### I Python

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

## CompactLeft

Deletes the columns of a specified range that match a filter expressed as a Calc formula. The filter is applied to each column to decide whether it will be deleted or not.

The deleted column can be limited to the height of the specified range or span to the height of the entire sheet, thus deleting whole columns.

This method returns a string with the range address of the compacted range. If all columns are deleted, then an empty string is returned.

If a range of cells is selected, calling this method will not impact the selection.

### Syntaks:

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

### Parametre:

range: The range from which columns will be deleted, as a string.

wholecolumn: If this option is set to True the entire column will be deleted from the sheet. The default value is False, which means that the deleted column will be limited to the height of the specified range.

filterformula: The filter to be applied to each column to determine whether or not it will be deleted. The filter is expressed as a Calc formula that should be applied to the first column. When the formula returns True for a column, that column will be deleted. The default filter deletes all empty columns.

For example, suppose range A1:J200 is selected (height = 200), so the default formula is =(COUNTBLANK(A1:A200)=200). This means that if all 200 cells are empty in the first column (Column A), then the column is deleted. Note that the formula is expressed with respect to the first column only. Internally the CompactLeft method will generalize this formula for all the remaining columns.

### Eksempel:

##### I Basic

        ' Delete all empty columns in the range G1:L10 from Sheet1
        newrange = oDoc.CompactLeft("Sheet1.G1:L10")
        ' The example below is similar, but the entire column is deleted from the sheet
        newrange = oDoc.CompactLeft("Sheet1.G1:L10", WholeColumn := True)
        ' Deletes all columns where the first row is marked with an "X"
        newrange = oDoc.CompactLeft("Sheet1.G1:L10", FilterFormula := "=(G1=""X"")")
        ' Deletes all columns where the sum of values in the column is odd
        newrange = oDoc.CompactLeft("Sheet1.G1:L10", FilterFormula := "=(MOD(SUM(G1:G10);2)=1)")

##### I Python

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

## CompactUp

Deletes the rows of a specified range that match a filter expressed as a Calc formula. The filter is applied to each row to decide whether it will be deleted or not.

The deleted rows can be limited to the width of the specified range or span to the width of the entire sheet, thus deleting whole rows.

This method returns a string with the range address of the compacted range. If all rows are deleted, then an empty string is returned.

If a range of cells is selected, calling this method will not impact the selection.

### Syntaks:

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

### Parametre:

range: The range from which rows will be deleted, as a string.

wholerow: If this option is set to True the entire row will be deleted from the sheet. The default value is False, which means that the deleted row will be limited to the width of the specified range.

filterformula: The filter to be applied to each row to determine whether or not it will be deleted. The filter is expressed as a Calc formula that should be applied to the first row. When the formula returns True for a row, that row will be deleted. The default filter deletes all empty rows.

For example, suppose range A1:J200 is selected (width = 10), so the default formula is =(COUNTBLANK(A1:J1)=10). This means that if all 10 cells are empty in the first row (Row 1), then the row is deleted. Note that the formula is expressed with respect to the first row only. Internally the CompactUp method will generalize this formula for all the remaining rows.

### Eksempel:

##### I Basic

        ' Delete all empty rows in the range G1:L10 from Sheet1
        newrange = oDoc.CompactUp("Sheet1.G1:L10")
        ' The example below is similar, but the entire row is deleted from the sheet
        newrange = oDoc.CompactUp("Sheet1.G1:L10", WholeRow := True)
        ' Deletes all rows where the first column is marked with an "X"
        newrange = oDoc.CompactUp("Sheet1.G1:L10", FilterFormula := "=(G1=""X"")")
        ' Deletes all rows where the sum of values in the row is odd
        newrange = oDoc.CompactUp("Sheet1.G1:L10", FilterFormula := "=(MOD(SUM(G1:L1);2)=1)")

##### I Python

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

## CopySheet

Kopierer et spesifisert ark før et eksisterende ark eller på slutten av listen over ark. Arket som skal kopieres kan være inne i ethvert åpent Calc-dokument. Returnerer Sann hvis vellykket.

### Syntaks:

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

### Parametre:

arknavn: Navnet på arket som skal kopieres som en streng eller dets referanse som et objekt.

nyttnavn: Navnet på arket som skal settes inn. Navnet må ikke være i bruk i dokumentet.

foranark: Navnet (strengen) eller indeksen (numerisk, fra 1) på arket som det kopierte arket skal settes inn før. Dette argumentet er valgfritt, og standard oppførsel er å legge til det kopierte arket på den siste posisjonen.

### Eksempel:

##### I Basic

Følgende eksempel lager en kopi av arket "SheetX" og plasserer det som det siste arket i gjeldende dokument. Navnet på det kopierte arket er "SheetY".

        Dim oDoc as Object
        Henter dokumentobjektet til det aktive vinduet
        Set oDoc = CreateScriptService("Calc")
        oDoc.CopySheet("SheetX", "SheetY")

Eksemplet nedenfor kopierer "SheetX" fra "FileA.ods" og limer det inn på den siste posisjonen til "FileB.ods" med navnet "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")

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

For å kopiere ark mellom åpne dokumenter, bruk CopySheet. For å kopiere ark fra dokumenter som er lukket, bruk CopySheetFromFile.

## CopySheetFromFile

Kopierer et spesifisert ark fra et lukket Calc-dokument og limer det inn før et eksisterende ark eller på slutten av listen over ark i filen referert til av et Dokument-objekt.

Hvis filen ikke eksisterer, oppstår det en feil. Hvis filen ikke er en gyldig Calc-fil, settes det inn et tomt ark. Hvis kildearket ikke finnes i inndatafilen, settes det inn en feilmelding øverst på det nylig limte arket.

### Syntaks:

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

### Parametre:

filnavn: Identifiserer filen som skal åpnes. Den må følge SF_FileSystem.FileNaming-notasjonen. Filen må ikke være beskyttet med passord.

arknavn: Navnet på arket som skal kopieres som en streng.

newname: Navnet på det kopierte arket som skal settes inn i dokumentet. Navnet må ikke være i bruk i dokumentet.

førark: Navnet (strengen) eller indeksen (numerisk, fra 1) på arket som det kopierte arket skal settes inn før. Dette argumentet er valgfritt, og standard oppførsel er å legge til det kopierte arket på den siste posisjonen.

### Eksempel:

Følgende eksempel kopierer "SheetX" fra "myFile.ods" og limer det inn i dokumentet referert til av "oDoc" som "SheetY" ved den første posisjonen.

##### I Basic

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

##### I Python

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

## CopyToCell

Kopierer et spesifisert kildeområde (verdier, formler og formater) til et målområde eller celle. Metoden reproduserer virkemåten til en Kopier/Lim inn-operasjon fra et område til en enkelt celle.

Den returnerer en streng som representerer det modifiserte celleområdet. Størrelsen på det modifiserte området bestemmes fullt ut av størrelsen på kildeområdet.

Kildeområdet kan tilhøre et annet åpent dokument.

### Syntaks:

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

### Parametre:

kildeområde: Kildeområdet som en streng når det tilhører samme dokument eller som en referanse når det tilhører et annet åpent Calc-dokument.

destinationcell: Destinasjonscellen der det kopierte celleområdet skal limes inn, som en streng. Hvis et område er gitt, vurderes kun dens øverste venstre celle.

### Eksempel:

##### I Basic

Neste er et eksempel der kilden og destinasjonen er i samme fil:

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

Eksemplet nedenfor illustrerer hvordan du kopierer et område fra et annet åpent Calc-dokument:

        Dim ui as Variant : ui = CreateScriptService("UI")
        Dim oDocSource As Object, oDocDestination As Object
        'Åpne kildedokumentet i bakgrunnen (skjult)
        Set oDocSource = ui.OpenDocument("C:\SourceFile.ods", Hidden := True, ReadOnly := True)
        Set oDocDestination = CreateScriptService("Calc")
        oDocDestination.CopyToCell(oDocSource.Range("Sheet1.C2:C4"), "SheetT.A5")
        'Ikke glem å lukke kildedokumentet fordi det ble åpnet som skjult
        oDocSource.CloseDocument()

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

For å simulere en Kopier/ Lim inn fra et område til en enkelt celle, bruk KopierTilCelle. For å simulere en Kopier/ Lim inn fra et område til et større område (med de samme cellene som blir replikert flere ganger), bruk KopierTilOmråde.

## CopyToRange

Kopierer nedover og/eller mot høyre et spesifisert kildeområde (verdier, formler og formater) til et målområde. Metoden imiterer oppførselen til en Kopier/Lim inn-operasjon fra et kildeområde til et større målområde.

- Hvis høyden (eller bredden) på destinasjonsområdet er > 1 rad (eller kolonne), må høyden (eller bredden) på kilden være <= høyden (eller bredden) på destinasjonen. Ellers skjer det ingenting.

- Hvis høyden (eller bredden) til destinasjonen er = 1, utvides destinasjonen nedover (eller mot høyre) opp til høyden (eller bredden) av kildeområdet.

Metoden returnerer en streng som representerer det modifiserte celleområdet.

Kildeområdet kan tilhøre et annet åpent dokument.

### Syntaks:

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

### Parametre:

kildeområde: Kildeområdet som en streng når det tilhører samme dokument eller som en referanse når det tilhører et annet åpent Calc-dokument.

destinationrange: Destinasjonen for det kopierte celleområdet, som en streng.

### Eksempel:

##### I Basic

Kopier innenfor samme dokument:

        oDoc.CopyToRange("SheetX.A1:F10", "SheetY.C5:J5")
        ' Returnerer en områdestreng: "$SheetY.$C$5:$J$14"

Kopier fra en fil til en annen:

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

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

Oppretter et nytt diagramobjekt som viser dataene i det angitte området. Det returnerte kartobjektet kan manipuleres ytterligere ved å bruke Diagram-tjenesten.

### Syntaks:

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

### Parametre:

diagramnavn: Det brukerdefinerte navnet på diagrammet som skal opprettes. Navnet må være unikt i samme ark.

arknavn: Navnet på arket der diagrammet skal plasseres.

område: Området som skal brukes som datakilde for diagrammet. Området kan referere til et hvilket som helst ark i Calc-dokumentet.

kolonnehode: Når True, brukes den øverste raden i området som etiketter for kategoriaksen eller forklaringen (Standard = Usann).

radhoder: Når Sann, brukes kolonnen lengst til venstre i området som etiketter for kategoriaksen eller forklaringen. (Standard = Usann).

### Eksempel:

Eksemplene nedenfor i Basic og Python lager et diagram ved å bruke dataene i området "A1:B5" til "Ark1" og plasser diagrammet i "Ark2".

##### I Basic

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

##### I Python

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

Se hjelpesiden om ScriptForges Diagramjeneste for å lære mer hvordan du kan ytterligere manipulere diagramobjekter. Det er mulig å endre egenskaper som diagramtype, diagram- og aksetitler og diagramposisjon.

## CreatePivotTable

Creates a new pivot table with the properties defined by the arguments passed to the method.

A name must be provided for the pivot table. If a pivot table with the same name already exists in the targeted sheet, it will be replaced without warning.

This method returns a string containing the range where the new pivot table was placed.

### Syntaks:

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

### Parametre:

pivottablename: The user-defined name of the new pivot table.

sourcerange: The range containing the raw data, as a string. It is assumed that the first row contains the field names that are used by the pivot table.

targetcell: The top-left cell where the new pivot table will be placed. If a range is specified, only its top-left cell is considered.

datafields: It can be either a single string or an array containing strings that define field names and functions to be applied. When an array is specified, it must follow the syntax Array("FieldName[;Function]", ...).

The allowed functions are: Sum, Count, Average, Max, Min, Product, CountNums, StDev, StDevP, Var, VarP and Median. Function names must be provided in English. When all values are numerical, Sum is the default function, otherwise the default function is Count.

rowfields: A single string or an array with the field names that will be used as the pivot table rows.

columnfields: A single string or an array with the field names that will be used as the pivot table columns.

filterbutton: Determines whether a filter button will be displayed above the pivot table (Default = True).

rowtotals: Specifies if a separate column for row totals will be added to the pivot table (Default = True).

columntotals Specifies if a separate row for column totals will be added to the pivot table (Default = True)

### Eksempel:

##### I 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"), _ ' Three data fields
            "Item", _ ' A single row field
            Array("State", "Team"), False) ' Two column fields

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

To learn more about Pivot Tables in LibreOffice Calc, read the Pivot Table help page.

## DAvg, DCount, DMax, DMin and DSum

Bruk funksjonene Gjennomsnitt, Tell, Maks, Min og Sum, henholdsvis på alle cellene som inneholder numeriske verdier i et gitt område.

### Syntaks:

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

### Parametre:

område: Området som funksjonen skal brukes på, som en streng.

### Eksempel:

Eksemplet nedenfor bruker Sum-funksjonen på området "A1:A1000" for det valgte arket:

##### I Basic

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

##### I Python

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

Celler i det gitte området som inneholder tekst vil bli ignorert av alle disse funksjonene. For eksempel vil DCount-metoden ikke telle celler med tekst, kun numeriske celler.

## ExportRangeToFile

Exports the specified range as an image or PDF file.

This method returns True if the destination file was successfully saved.

Hidden rows or columns in the specified range are not exported to the destination file.

### Syntaks:

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

### Parametre:

range: A sheet name or a cell range to be exported, as a string.

filename: The name of the file to be saved. It must follow the SF_FileSystem.FileNaming notation.

imagetype: Identifies the destination file type. Possible values are "jpeg", "pdf" (default) and "png".

overwrite: When set to True, the destination file may be overwritten (Default = False).

### Eksempel:

##### I Basic

        ' Exports the entire sheet as a PDF file
        oDoc.ExportRangeToFile("SheetX", "C:\Temp\image.pdf")
        ' Exports the range as a PNG file and overwrites the destination file if it exists
        oDoc.ExportRangeToFile("SheetX.A1:D10", "C:\Temp\image.png", "png", Overwrite := True)

##### I Python

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

## Forms

Avhengig av parametrene som er gitt, vil denne metoden returnere:

- En nullbasert matrise (eller en tuppel i Python) med navnene på alle skjemaene i et gitt ark (hvis form-argumentet er fraværende)

- En SFDocuments.Form tjenesteforekomst som representerer skjemaet angitt som argument.

### Syntaks:

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

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

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

### Parametre:

arknavn: Navnet på arket, som en streng, som skjemaet vil bli hentet fra.

skjema: Navnet eller indeksen som tilsvarer et skjema som er lagret i det angitte arket. Hvis dette argumentet er fraværende, vil metoden returnere en liste med navnene på alle tilgjengelige skjemaer i arket.

### Eksempel:

I de følgende eksemplene får den første linjen navnene på alle skjemaer som er lagret i "Ark1", og den andre linjen henter Skjema-objektet til skjemaet kalt "Skjema_A" som er lagret i "Ark1".

##### I Basic

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

##### I Python

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

## GetColumnName

Konverterer et kolonnenummer mellom 1 og 1024 til dens tilsvarende bokstav (kolonne 'A', 'B', ..., 'AMJ'). Hvis det gitte kolonnenummeret er utenfor det tillatte området, returneres en streng med null lengde.

### Syntaks:

svc.GetColumnName(columnnumber: int): str

### Parametre:

kolonnenummer: Kolonnenummeret som en heltallsverdi i intervallet 1 ... 1024.

### Eksempel:

##### I Basic

Viser en meldingsboks med navnet på den tredje kolonnen, som som standard er "C".

        MsgBox oDoc.GetColumnName(3)

##### I Python

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

Maksimalt antall kolonner tillatt på et Calc-ark er 1024.

## GetFormula

Få formelen(e) lagret i det gitte celleområdet som en enkelt streng, en 1D eller en 2D rekke strenger.

### Syntaks:

svc.GetFormula(range: str): any

### Parametre:

område: Området hvor formlene skal hentes fra, som en streng.

### Eksempel:

##### I Basic

Følgende eksempel returnerer en 3 x 2 matrise med formlene i området "A1:B3" (3 rader x 2 kolonner):

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

##### I Python

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

## GetValue

Få verdien(e) lagret i det gitte celleområdet som en enkelt verdi, en 1D-matrise eller en 2D-matrise. Alle verdier er enten doble eller strenger.

### Syntaks:

svc.GetValue(range: str): any

### Parametre:

område: Området hvor du skal hente verdiene fra, som en streng.

### Eksempel:

##### I Basic

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

##### I Python

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

Hvis en celle inneholder en dato, vil tallet som tilsvarer den datoen bli returnert. For å konvertere numeriske verdier til datoer i grunnleggende skript, bruk den grunnleggende CDate innebygde funksjon. I Python-skript bruker du CDate-funksjonen fra Basic-funksjonen > tjeneste.

## ImportFromCSVFile

Importerer innholdet i en CSV-formatert tekstfil og plasserer den på en gitt destinasjonscelle.

Destinasjonsområdet tømmes for alt innhold og formater før innholdet i CSV-filen settes inn. Størrelsen på det modifiserte området bestemmes fullt ut av innholdet i inndatafilen.

Metoden returnerer en streng som representerer det modifiserte celleområdet.

### Syntaks:

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

### Parametre:

filnavn: Identifiserer filen som skal åpnes. Den må følge SF_FileSystem.FileNaming-notasjonen.

destinationcell: Destinasjonscellen for å sette inn importerte data, som en streng. Hvis det i stedet angis et område, vurderes bare dens øverste venstre celle.

filteralternativer: Argumentene for CSV-inndatafilteret. Standardfilteret gjør følgende forutsetninger:

- Inndatafilens koding er UTF8.

- Feltseparatoren er et komma, et semikolon eller et tabulatortegn.

- Strengavgrensningstegnet er det doble anførselstegn (").

- Alle linjer er inkludert.

- Strenger i anførselstegn er formatert som tekst.

- Spesielle tall blir oppdaget.

- Alle kolonner antas å være tekster, bortsett fra hvis de gjenkjennes som gyldige tall.

- Språket er engelsk/amerikansk, noe som betyr at desimalskilletegn er "." og tusenskilletegn er ",".

### Eksempel:

##### I Basic

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

##### I Python

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

For å lære mer om CSV-filteralternativene, se hjelpesiden for CSV-filteralternativer.

## ImportFromDatabase

Importerer innholdet i en databasetabell, spørring eller resultatsett, dvs. resultatet av en SELECT SQL-kommando, setter den inn i en destinasjonscelle.

Destinasjonsområdet tømmes for alt innhold og formater før det importerte innholdet settes inn. Størrelsen på det modifiserte området bestemmes fullt ut av innholdet i tabellen eller spørringen.

Metoden returnerer Sann når importen var vellykket.

### Syntaks:

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

### Parametre:

filnavn: Identifiserer filen som skal åpnes. Den må følge SF_FileSystem.FileNaming-notasjonen.

registreringsnavn: Navnet som skal brukes for å finne databasen i databaseregisteret. Dette argumentet ignoreres hvis et filnavn er oppgitt.

destinationcell: Destinasjonen for de importerte dataene, som en streng. Hvis et område er gitt, vurderes kun dens øverste venstre celle.

sqlcommand: Et tabell- eller spørringsnavn (uten anførselstegn eller hakeparenteser) eller en SELECT SQL-setning der tabell- og feltnavn kan være omgitt av hakeparenteser eller anførselstegn for å forbedre lesbarheten.

directsql: Når True, sendes SQL-kommandoen til databasemotoren uten forhåndsanalyse. Standard er Usann. Argumentet ignoreres for tabeller. For spørringer er det valgte alternativet det som ble angitt da spørringen ble definert.

### Eksempel:

##### I Basic

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

##### I Python

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

## InsertSheet

Setter inn et nytt tomt ark før et eksisterende ark eller på slutten av listen over ark.

### Syntaks:

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

### Parametre:

arknavn: Navnet på det nye arket.

beforesheet: Navnet (strengen) eller indeksen (numerisk, fra 1) til arket som det nye arket skal settes inn før. Dette argumentet er valgfritt, og standard oppførsel er å sette inn arket på den siste posisjonen.

### Eksempel:

Følgende eksempel setter inn et nytt tomt ark kalt "ArkX" og plasserer det før "ArkY":

##### I Basic

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

##### I Python

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

## MoveRange

Flytter et spesifisert kildeområde til et målområde med celler. Metoden returnerer en streng som representerer det modifiserte celleområdet. Dimensjonen til det modifiserte området er fullt ut bestemt av størrelsen på kildeområdet.

### Syntaks:

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

### Parametre:

kilde: Kildeområdet for celler, som en streng.

destinasjon: Destinasjonscellen, som en streng. Hvis et område er gitt, anses dens øverste venstre celle som destinasjonen.

### Eksempel:

##### I Basic

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

##### I Python

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

## MoveSheet

Flytter et eksisterende ark og plasserer det foran et spesifisert ark eller på slutten av listen over ark.

### Syntaks:

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

### Parametre:

arknavn: Navnet på arket som skal flyttes. Arket må eksistere eller et unntak oppstår.

beforesheet: Navnet (strengen) eller indeksen (numerisk, fra 1) til arket som det originale arket skal plasseres foran. Dette argumentet er valgfritt, og standard oppførsel er å flytte arket til siste posisjon.

### Eksempel:

Eksemplet nedenfor flytter det eksisterende arket "SheetS" og plasserer det før "ShettY":

##### I Basic

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

##### I Python

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

## Offset

Returnerer et nytt område (som en streng) forskjøvet med et visst antall rader og kolonner fra et gitt område.

Denne metoden har samme oppførsel som den homonyme Calcs Offset-funksjon.

### Syntaks:

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

### Parametre:

referanse: Området, som en streng, som metoden vil bruke som referanse for å utføre offset-operasjonen.

rader: Antall rader som startområdet forskyves med oppover (negativ verdi) eller nedover (positiv verdi). Bruk 0 (standard) for å bli i samme rad.

kolonner: Antall kolonner som startområdet forskyves med til venstre (negativ verdi) eller til høyre (positiv verdi). Bruk 0 (standard) for å bli i samme kolonne.

høyde: Den vertikale høyden for et område som starter ved den nye rekkeviddeposisjonen. Utelat dette argumentet når ingen vertikal endring av størrelse er nødvendig.

bredde: Den horisontale bredden for et område som starter ved den nye rekkeviddeposisjonen. Utelat dette argumentet når ingen horisontal størrelseendring er nødvendig.

Argumenter rader og kolonner må ikke føre til null eller negativ startrad eller kolonne.

Argumenter høyde og bredde må ikke føre til null eller negativt antall rader eller kolonner.

### Eksempel:

##### I Basic

        oDoc.Offset("A1", 2, 2)
        'SheetX.$C$3 (A1 flyttet med to rader og to kolonner nedover)
        oDoc.Offset("A1", 2, 2, 5, 6)
        'SheetX.$C$3:$H$7 (A1 forskjøvet med to rader og kolonner med en bredde på 5 rader og 6 kolonner)

##### I Python

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

## OpenRangeSelector

Åpner en ikke-modal dialogboks som kan brukes til å velge et område i dokumentet og returnerer en streng som inneholder det valgte området.

Denne metoden åpner den samme dialogboksen som brukes av LibreOffice når Minsk-knappen trykkes. For eksempel har Verktøy - Målsøk-dialogen en Minsk-knapp til høyre for Formelcelle-feltet.

Denne metoden endrer ikke gjeldende valg.

### Syntaks:

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

### Parametre:

tittel: Tittelen på dialogboksen, som en streng.

utvalg: Et valgfritt område som først velges når dialogboksen vises.

enkeltcelle: Når Sann (standard) er kun enkeltcellevalg tillatt. Når Usann er omrxdevalg tillatt.

stengettervalg: Når Sann (standard) lukkes dialogen umiddelbart etter at valget er gjort. Når Usann kan brukeren endre valget så mange ganger som nødvendig og deretter lukke dialogen manuelt.

### Eksempel:

##### I Basic

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

##### I Python

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

## Printf

Returnerer inndatastrengen etter å ha erstattet dens token-tegn med verdiene deres i et gitt område.

Denne metoden endrer ikke gjeldende valg.

Denne metoden kan brukes til raskt å trekke ut bestemte deler av et områdenavn, for eksempel arknavnet eller første cellekolonne og rad, og bruke dem til å lage en ny områdeadresse.

### Syntaks:

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

### Parametre:

inputstr: The string containing the tokens that will be replaced by the corresponding values in range.

range: A RangeName from which values will be extracted. If it contains a sheet name, the sheet must exist.

tokencharacter: Character used to identify tokens. By default "%" is the token character. The following tokens are accepted:

- %S - The sheet name containing the range, including single quotes when necessary.

- %R1 - The row number of the top left cell of the range.

- %C1 - The column letter of the top left cell of the range.

- %R2 - The row number of the bottom right cell of the range.

- %C2 - The column letter of the bottom right cell of the range.

### Eksempel:

##### I Basic

The example below extracts each element of the RangeName defined in sRange and uses them to compose a message.

        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)

The Printf method can be combined with SetFormula to create formulas over multiple cells. For instance, consider a table with numeric values in the range "A1:E10" from which formulas are to be created to sum the values in each row and place the results in the range "F1:F10":

        Dim sFormula as String, sRange as String
        sRange = "A1:E10"
        ' Note the use of the "$" character
        sFormula = "=SUM($%C1%R1:$%C2%R1)"
        oDoc.SetFormula("F1:F10", oDoc.Printf(sFormula, sRange))

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

This method sends the contents of the given sheet to the default printer or to the printer defined by the SetPrinter method of the Document service.

Returns True if the sheet was successfully printed.

### Syntaks:

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

### Parametre:

sheetname: The sheet to print, default is the active sheet.

pages: The pages to print as a string, like in the user interface. Example: "1-4;10;15-18". Default is all pages.

copies: The number of copies. Default is 1.

### Eksempel:

##### I Basic

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

##### I Python

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

## RemoveSheet

Removes an existing sheet from the document.

### Syntaks:

svc.RemoveSheet(sheetname: str): bool

### Parametre:

sheetname: The name of the sheet to remove.

### Eksempel:

##### I Basic

        oDoc.RemoveSheet("SheetY")

##### I Python

        myDoc.RemoveSheet("SheetY")

## RenameSheet

Renames the given sheet and returns True if successful.

### Syntaks:

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

### Parametre:

sheetname: The name of the sheet to rename.

newname: the new name of the sheet. It must not exist yet.

### Eksempel:

This example renames the active sheet to "SheetY":

##### I Basic

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

##### I Python

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

## SetArray

Stores the given value starting from a specified target cell. The updated area expands itself from the target cell or from the top-left corner of the given range to accommodate the size of the input value argument. Vectors are always expanded vertically.

The method returns a string representing the modified area as a range of cells.

### Syntaks:

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

### Parametre:

targetcell: The cell or a range as a string from where to start to store the given value.

value: A scalar, a vector or an array (in Python, one or two-dimensional lists and tuples) with the new values to be stored from the target cell or from the top-left corner of the range if targetcell is a range. The new values must be strings, numeric values or dates. Other types will cause the corresponding cells to be emptied.

### Eksempel:

##### I Basic

The following example uses the builtin DimArray function to create an array and then store it in cell "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)

This example uses the RangeInit method of the ScriptForge Array service to create an array with values that are then stored from cell "A1" and downwards.

        'Fill 1st column with values from 1 to 1000
        oDoc.SetArray("Sheet1.A1", SF_Array.RangeInit(1, 1000))

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

To dump the full contents of an array in a sheet, use SetArray. To dump the contents of an array only within the boundaries of the targeted range of cells, use SetValue.

## SetValue

Stores the given value in the specified range. The size of the modified area is equal to the size of the target range.

The method returns a string representing the modified area as a range of cells.

### Syntaks:

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

### Parametre:

targetrange: The range where to store the given value, as a string.

value: A scalar, a vector or an array with the new values for each cell of the range. The new values must be strings, numeric values or dates. Other types will cause the corresponding cells to be emptied.

The full range is updated and the remainder of the sheet is left unchanged. If the size of value is smaller than the size of targetrange, then the remaining cells will be emptied.

If the size of value is larger than the size of targetrange, then value is only partially copied until it fills the size of targetrange.

Vectors are expanded vertically, except if targetrange has a height of exactly 1 row.

### Eksempel:

##### I Basic

        oDoc.SetValue("A1", 2)
        'Below the Value array is smaller than the TargetRange (remaining cells are emptied)
        oDoc.SetValue("A1:F1", Array(1, 2, 3))
        'Below the Value and TargetRange have the same size
        oDoc.SetValue("A1:D2", SF_Array.AppendRow(Array(1, 2, 3, 4), Array(5, 6, 7, 8)))

If you want to fill a single row with values, you can use the Offset function. In the example below, consider that arrData is a one-dimensional array:

        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)

##### I Python

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

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

## SetCellStyle

Applies the specified cell style to the given target range. The full range is updated and the remainder of the sheet is left untouched. If the cell style does not exist, an error is raised.

The method returns a string representing the modified area as a range of cells.

### Syntaks:

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

### Parametre:

targetrange: The range to which the style will be applied, as a string.

style: The name of the cell style to apply.

### Eksempel:

##### I Basic

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

##### I Python

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

## SetFormula

Inserts the given (array of) formula(s) in the specified range. The size of the modified area is equal to the size of the range.

The method returns a string representing the modified area as a range of cells.

### Syntaks:

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

### Parametre:

targetrange: The range to insert the formulas, as a string.

formula: A string, a vector or an array of strings with the new formulas for each cell in the target range.

The full range is updated and the remainder of the sheet is left unchanged.

If the given formula is a string, the unique formula is pasted along the whole range with adjustment of the relative references.

If the size of formula is smaller than the size of targetrange, then the remaining cells are emptied.

If the size of formula is larger than the size of targetrange, then the formulas are only partially copied until it fills the size of targetrange.

Vectors are always expanded vertically, except if targetrange has a height of exactly 1 row.

### Eksempel:

##### I Basic

        oDoc.SetFormula("A1", "=A2")
        'Horizontal vector, partially empty
        oDoc.SetFormula("A1:F1", Array("=A2", "=B2", "=C2+10"))
        'D2 contains the formula "=H2"
        oDoc.SetFormula("A1:D2", "=E1")

##### I Python

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

## ShiftDown

Moves a given range of cells downwards by inserting empty rows. The current selection is not affected.

Depending on the value of the wholerow argument the inserted rows can either span the width of the specified range or span all columns in the row.

This method returns a string representing the new location of the initial range.

If the shifted range exceeds the sheet edges, then nothing happens.

### Syntaks:

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

### Parametre:

range: The range above which rows will be inserted, as a string.

wholerow: If set to False (default), then the width of the inserted rows will be the same as the width of the specified range. Otherwise, the inserted row will span all columns in the sheet.

rows: The number of rows to be inserted. The default value is the height of the original range. The number of rows must be a positive number.

### Eksempel:

##### I Basic

        ' Moves the range "A3:D3" down by one row; affects only columns A to D
        oDoc.ShiftDown("A3:D3")
        ' The inserted row spans all columns in the sheet
        oDoc.ShiftDown("A3:D3", WholeRow := True)
        ' Moves the range "A3:D3" down by five rows
        oDoc.ShiftDown("A3:D3", Rows := 5)
        ' Moves the range "A3:D10" down by two rows and shows the new location of the original range
        Dim sNewRange as String
        sNewRange = oDoc.ShiftDown("A3:D10", Rows := 2)
        MsgBox sNewRange   ' $Sheet1.$A$5:$D$12

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

Deletes the leftmost columns of a given range and moves to the left all cells to the right of the affected range. The current selection is not affected.

Depending on the value of the wholecolumn argument the deleted columns can either span the height of the specified range or span all rows in the column.

This method returns a string representing the location of the remaining portion of the initial range. If all cells in the original range have been deleted, then an empty string is returned.

### Syntaks:

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

### Parametre:

range: The range from which cells will be deleted, as a string.

wholecolumn: If set to False (default), then the height of the deleted columns will be the same as the height of the specified range. Otherwise, the deleted columns will span all rows in the sheet.

columns: The number of columns to be deleted from the specified range. The default value is the width of the original range, which is also the maximum value of this argument.

### Eksempel:

##### I Basic

        ' Deletes the range "B3:B6"; moves left all cells to the right
        oDoc.ShiftLeft("B3:B6")
        ' Deletes the first column in the range "A3:D6"
        oDoc.ShiftLeft("A3:D6", Columns := 1)
        ' The deleted columns (A to D) spans all rows in the sheet
        oDoc.ShiftLeft("A3:D6", WholeColumn := True)

##### I Python

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

## ShiftUp

Deletes the topmost rows of a given range and moves upwards all cells below the affected range. The current selection is not affected.

Depending on the value of the wholerow argument the deleted rows can either span the width of the specified range or span all columns in the row.

This method returns a string representing the location of the remaining portion of the initial range. If all cells in the original range have been deleted, then an empty string is returned.

### Syntaks:

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

### Parametre:

range: The range from which cells will be deleted, as a string.

wholerow: If set to False (default), then the width of the deleted rows will be the same as the width of the specified range. Otherwise, the deleted row will span all columns in the sheet.

rows: The number of rows to be deleted from the specified range. The default value is the height of the original range, which is also the maximum value of this argument.

### Eksempel:

##### I Basic

        ' Deletes the range "A3:D3"; moves all cells below it by one row up
        oDoc.ShiftUp("A3:D3")
        ' Deletes the first row in the range "A3:D6"
        oDoc.ShiftUp("A3:D6", Rows := 1)
        ' The deleted rows spans all columns in the sheet
        oDoc.ShiftUp("A3:D6", WholeRow := True)

##### I Python

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

## ShiftRight

Moves a given range of cells to the right by inserting empty columns. The current selection is not affected.

Depending on the value of the wholecolumn argument the inserted columns can either span the height of the specified range or span all rows in the column.

This method returns a string representing the new location of the initial range.

If the shifted range exceeds the sheet edges, then nothing happens.

### Syntaks:

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

### Parametre:

range: The range which will have empty columns inserted to its left, as a string.

wholecolumn: If set to False (default), then the height of the inserted columns will be the same as the height of the specified range. Otherwise, the inserted columns will span all rows in the sheet.

columns: The number of columns to be inserted. The default value is the width of the original range.

### Eksempel:

##### I Basic

        ' Moves the range "A3:A6" right by one column; affects only rows 3 to 6
        oDoc.ShiftRight("A3:A6")
        ' Moves the range "A3:A6" right by five columns
        oDoc.ShiftRight("A3:A6", Columns := 5)
        ' The inserted column spans all rows in the sheet
        oDoc.ShiftRight("A3:A6", WholeColumn := True)

##### I Python

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

## SortRange

Sorts the given range based on up to 3 columns/rows. The sorting order may vary by column/row. It returns a string representing the modified range of cells. The size of the modified area is fully determined by the size of the source area.

### Syntaks:

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

### Parametre:

range: The range to be sorted, as a string.

sortkeys: A scalar (if 1 column/row) or an array of column/row numbers starting from 1. The maximum number of keys is 3.

sortorder: A scalar or an array of strings containing the values "ASC" (ascending), "DESC" (descending) or "" (which defaults to ascending). Each item is paired with the corresponding item in sortkeys. If the sortorder array is shorter than sortkeys, the remaining keys are sorted in ascending order.

destinationcell: The destination cell of the sorted range of cells, as a string. If a range is given, only its top-left cell is considered. By default the source Range is overwritten.

containsheader: When True, the first row/column is not sorted.

casesensitive: Only for string comparisons. Default = False

sortcolumns: When True, the columns are sorted from left to right. Default = False : rows are sorted from top to bottom.

### Eksempel:

##### I Basic

        'Sort range based on columns A (ascending) and C (descending)
        oDoc.SortRange("A2:J200", Array(1, 3), Array("ASC", "DESC"), CaseSensitive := True)

##### I Python

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

Alle ScriptForge Grunnleggende rutiner eller identifikatorer som er prefikset med et understrekingstegn "_" er reservert for intern bruk. De er ikke ment å brukes i grunnleggende makroer eller Python-skript.

Lignende emner

SFDocuments.Chart service

SFDocuments.Document service

ScriptForge.UI service