SFDocuments.Calc tjeneste

The SFDocuments library provides a number of methods and properties to facilitate the management and handling of LibreOffice Calc documents.

Some methods are generic for all types of documents and are inherited from the Document service, whereas other methods are specific for the SF_Calc module.

The SF_Calc module is focused on:

Tjenestepåkallelse

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

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

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

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

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:

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 = svcUI.OpenDocument(r"C:\Documents\FileA.ods", hidden = True, readonly = True)
    docB = svcUI.OpenDocument(r"C:\Documents\FileB.ods")
    docB.CopyToRange(docA.Range("SheetX.D4:F8"), "D2:F6")
  

SheetName

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 i et område (standard = det aktive arket). Omkringliggende enkeltanførselstegn og $-tegn er tillatt, men ignoreres.

tip

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


Eksempler på gyldige områder

1) '$ArkX'.D2
2) $D$2

En enkelt celle

1) '$ArkX'.D2:F6
2) D2:D10

Enkelt område med flere celler

'$ArkX'.*

Alle brukte celler i det aktuelle arket

1) '$Sheet'.A:A (kolonne A)
2) 3:5 (rad 3 til 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

Type

Beskrivelse

CurrentSelection

Nei

Ingen

Strenger eller en rekke strenger

The single selected range as a string or the list of selected ranges as an array

Height

Ja

Områdenavn som streng

Long

The number of rows (>= 1) in the given range

LastCell

Ja

SheetName As String

String

The last used cell in 'A1' format in the given sheet

LastColumn

Ja

SheetName As String

Long

The last used column in the given sheet

LastRow

Ja

SheetName As String

Long

The last used row in the given sheet

Range

Ja

Områdenavn som streng

Object

A range reference that can be used as argument of methods like CopyToRange

Sheet

Ja

Arknavn som streng

Object

A sheet reference that can be used as argument of methods like CopySheet

Sheets

Ja

Ingen

Matrise med strenger

The list with the names of all existing sheets

Width

Ja

Områdenavn som streng

Long

The number of columns (>= 1) in the given range

XCellRange

Ja

Områdenavn som streng

Object

A com.sun.star.Table.XCellRange UNO object

XSpreadsheet

Ja

Arknavn som streng

Object

A com.sun.star.sheet.XSpreadsheet UNO object


tip

Visit LibreOffice API Documentation's website to learn more about XCellRange and XSpreadsheet UNO objects.


Metoder

Liste over metoder i Calc-tjenesten

Activate
ClearAll
ClearFormats
ClearValues
CopySheet
CopySheetFromFile
CopyToCell
CopyToRange
DAvg
DCount

DMax
DMin
DSum
Forms
GetColumnName
GetFormula
GetValue
ImportFromCSVFile
ImportFromDatabase
InsertSheet

MoveRange
MoveSheet
Offset
RemoveSheet
RenameSheet
SetArray
SetValue
SetCellStyle
SetFormula
SortRange


Activate

If the argument SheetName is provided, the given sheet is activated and it becomes the currently selected sheet. If the argument is absent, then the document window is activated.

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

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

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.


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

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 = svcUI.OpenDocument(r"C:\Documents\FileA.ods", hidden = True, readonly = True)
    docB = svcUI.OpenDocument(r"C:\Documents\FileB.ods")
    docB.CopySheet(docA.Sheet("SheetX"), "SheetY")
  
tip

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 = svcUI.OpenDocument(r"C:\Documents\SourceFile.ods", hidden = True, readonly = True)
    docDestination = CreateScriptService("Calc")
    docDestination.CopyToCell(docSource.Range("Sheet1.C2:C4"), "SheetT.A5")
    docSource.CloseDocument()
  
tip

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.

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 = svcUI.OpenDocument(r"C:\Documents\FileA.ods", hidden = True, readonly = True)
    docB = svcUI.OpenDocument(r"C:\Documents\FileB.ods")
    docB.CopyToRange(docA.Range("SheetX.A1:F10"), "SheetY.C5:J5")
  

DAvg, DCount, DMax, DMin and DSum

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

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.


Forms

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

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

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

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

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:

Eksempel:

I Basic

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

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

For å lære mer om CSV-filteralternativene, se Filteralternativer Wiki-siden .


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)
  

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

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

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

All ScriptForge Basic routines or identifiers that are prefixed with an underscore character "_" are reserved for internal use. They are not meant be used in Basic macros.