SFDocuments.Calc service

De gedeelde bibliotheek SFDocuments biedt een aantal methoden en eigenschappen om het beheer en de verwerking van LibreOfficeDev-documenten te vergemakkelijken.

De service SFDocuments.Calc is een subklasse van de service SFDocuments.Document. Alle methoden en eigenschappen die gedefinieerd zijn voor de service Document kunnen ook benaderd worden via een instantie van de service Calc.

De service Calc is gericht op:

note

Deze helppagina beschrijft methoden en eigenschappen die alleen van toepassing zijn op Calc-documenten.


Service aanroep

Voordat u de Calc-service gebruikt, moet de ScriptForge-bibliotheek worden geladen of geĆÆmporteerd:

note

• Basic macro's kunnen de bibliotheek ScriptForge laden met de instructie:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Python scripts kunnen de module scriptforge importeren met:
from scriptforge import CreateScriptService


De service Calc is nauw verwant aan de service UI van de ScriptForge-bibliotheek. Hieronder staan een paar voorbeelden van hoe de service Calc kan worden aangeroepen.

In BASIC

Het onderstaande codefragment maakt een service-instantie Calc die overeenkomt met het momenteel actieve Calc-document.


    Set oDoc = CreateScriptService("Calc")
  

Een andere manier om een instantie van de service Calc te maken, is door de service UI te gebruiken. In het volgende voorbeeld wordt een nieuw Calc-document gemaakt en is oDoc een Calc service-instantie:


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

Of gebruik de OpenDocument-methode van de UI-service:


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

Het is ook mogelijk om de service Calc te instantiƫren met behulp van de methodeCreateScriptService:


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

In het bovenstaande voorbeeld is "MyFile.ods" de naam van een geopend documentvenster. Als dit argument niet wordt opgegeven, wordt het actieve venster beschouwd.

Het wordt aanbevolen om na gebruik middelen vrij te maken:


    Set oDoc = oDoc.Dispose()
  

Als het document echter is gesloten met de methode CloseDocument, is het niet nodig om bronnen vrij te maken met het hierboven beschreven commando.

In Python

    myDoc = CreateScriptService("Calc")
  

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

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

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

Het gebruik van het voorvoegsel "SFDocuments." tijdens het aanroepen van de service is optioneel.


Definities

Veel methoden vereisen een "Blad" of een "Bereik" als argument. Enkele cellen worden beschouwd als een speciaal geval van een Bereik.

Beide kunnen worden uitgedrukt als een tekenreeks of als een referentie (= object), afhankelijk van de situatie:

Voorbeeld:

Het onderstaande voorbeeld kopieert gegevens van document A (geopend als alleen-lezen en verborgen) naar document B.

In BASIC

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

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

SheetName

Ofwel de bladnaam als een string of een object geproduceerd door de eigenschap .Sheet.

De sneltoets "~" (tilde) staat voor het huidige blad.

RangeName

Ofwel een tekenreeks die een reeks aaneengesloten cellen aanduidt die zich in een blad van de huidige instantie bevinden, of een object geproduceerd door de eigenschap .Range.

De sneltoets "~" (tilde) staat voor de huidige selectie of het eerst geselecteerde bereik als er meerdere bereiken zijn geselecteerd.

De sneltoets "*" staat voor alle gebruikte cellen.

De bladnaam is optioneel in een bereik (standaard = het actieve blad). Omliggende enkele aanhalingstekens en $-tekens zijn toegestaan, maar worden genegeerd.

tip

Met uitzondering van de eigenschap CurrentSelection, houdt de service Calc alleen rekening met enkele celbereiken.


Voorbeelden van geldige bereiken

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

Een enkele cel

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

Enkel bereik met meerdere cellen

'$BladX'.*

Alle gebruikte cellen in het gegeven blad

1) '$BladX'.A:A (kolom A)
2) 3:5 (rijen 3 tot 5)

Alle cellen in aaneengesloten kolommen of rijen tot aan de laatst gebruikte cel

mijnBereik

Een bereik met de naam "mijnBereik" op werkbladniveau

1) ~.eenBereik
2) BladX.eenBereik

Een bereiknaam op bladniveau

mijnDoc.Bereik("BladX.D2:F6")

Een bereik binnen het blad BladX in bestand dat is gekoppeld aan de Calc-instantie mijnDoc

~.~ of ~

De huidige selectie in het actieve blad


Eigenschappen

Alle eigenschappen die generiek zijn voor elk document, zijn impliciet ook van toepassing op Calc-documenten. Lees voor meer informatie de Documentservice Help-pagina.

De eigenschappen die specifiek beschikbaar zijn voor Calc-documenten zijn:

Naam

AlleenLezen

Argument

Retourtype:

Beschrijving

CurrentSelection

Nee

Geen

Tekenreeks of matrix van tekenreeksen

Het enkele geselecteerde bereik als een tekenreeks of de lijst met geselecteerde bereiken als een matrix.

FirstCell

Ja

Bladnaam of Bereiknaam als tekenreeks

String

Retourneert de eerste gebruikte cel in een bepaald bereik of blad.

FirstColumn

Ja

Bladnaam of bereiknaam als tekenreeks

Long

Retourneert het meest linkse kolomnummer in een bepaald bereik of blad.

FirstRow

Ja

Bladnaam of bereiknaam als tekenreeks

Long

Retourneert het bovenste rijnummer in een bepaald bereik of blad.

Height

Ja

Bereiknaam als tekenreeks

Long

Het aantal rijen (>=1) in het opgegeven bereik.

LastCell

Ja

Bladnaam of bereiknaam als tekenreeks

String

Retourneert de laatst gebruikte cel in een bepaald bereik of blad.

LastColumn

Ja

Bladnaam of bereiknaam als tekenreeks

Long

De laatst gebruikte kolom in een bepaald bereik of blad.

LastRow

Ja

Bladnaam of bereiknaam als tekenreeks

Long

De laatst gebruikte rij in een bepaald bereik of blad.

Range

Ja

Bereiknaam als tekenreeks

Object

Een bereikverwijzing die kan worden gebruikt als argument van methoden zoals CopyToRange.

Region

Ja

Bereiknaam als tekenreeks

String

Retourneert het adres van het kleinste gebied dat het opgegeven bereik bevat, zodat het gebied wordt omgeven door lege cellen of bladranden. Dit komt overeen met het toepassen van de snelkoppeling naar het opgegeven bereik.

Sheet

Ja

Bladnaam als tekenreeks

Object

Een bladverwijzing die kan worden gebruikt als argument voor methoden zoals CopySheet.

SheetName

Ja

Bereiknaam als tekenreeks

String

Retourneert de bladnaam van een bepaald bereikadres.

Sheets

Ja

Geen

Matrix van tekenreeksen

De lijst met de namen van alle bestaande bladen.

Width

Ja

Bereiknaam als tekenreeks

Long

Het aantal kolommen (>=1) in het opgegeven bereik.

XCellRange

Ja

Bereiknaam als tekenreeks

Object

Een com.sun.star.Table.XCellRange UNO-object.

XSheetCellCursor

Ja

Bereiknaam als tekenreeks

Object

Een com.sun.star.sheet.XSheetCellCursor UNO-object. Na het verplaatsen van de cursor kan het resulterende bereikadres worden geopend via de UNO-eigenschap AbsoluteName van het cursorobject, dat een tekenreekswaarde retourneert die kan worden gebruikt als argument voor eigenschappen en methoden van de Calc-service.

XSpreadsheet

Ja

Bladnaam als tekenreeks

Object

Een com.sun.star.sheet.XSpreadsheet UNO-object.


tip

Op de website LibreOfficeDev API Documentation vind u meer informatie over de XCellRange, XSheetCellCursor en XSpreadsheet UNO-objecten.


Methoden

Lijst met methoden in de Calc-service

A1Style
Activate
Charts
ClearAll
ClearFormats
ClearValues
CompactLeft
CompactUp
CopySheet
CopySheetFromFile
CopyToCell
CopyToRange
CreateChart
CreatePivotTable
DAvg

DCount
DMax
DMin
DSum
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

Retourneert een bereikadres als een tekenreeks op basis van bladcoƶrdinaten, d.w.z. rij- en kolomnummers.

Als alleen een paar coƶrdinaten wordt gegeven, wordt een adres naar een enkele cel geretourneerd. Aanvullende argumenten kunnen de cel rechtsonder van een rechthoekig bereik specificeren.

Syntaxis:

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

Parameters:

rij1, kolom1: geef de rij- en kolomnummers op van de cel linksboven in het te beschouwen bereik. Rij- en kolomnummers beginnen bij 1.

rij2, kolom2: specificeer de rij- en kolomnummers van de cel rechtsonder in het te beschouwen bereik. Als deze argumenten niet worden opgegeven, of als waarden kleiner dan rij1 en kolom1 worden gegeven, dan wordt het adres van het enkele celbereik vertegenwoordigd door rij1 en kolom1 wordt geretourneerd.

bladnaam: de naam van het blad dat moet worden toegevoegd aan het geretourneerde bereikadres. Het blad moet bestaan. De standaardwaarde is "~" die overeenkomt met het huidige actieve blad.

Voorbeeld:

De onderstaande voorbeelden in Basic en Python gaan ervan uit dat "Blad1" het momenteel actieve blad is.

In BASIC

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

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

De methode A1Style kan worden gecombineerd met een van de vele eigenschappen en methoden van de Calc-service die een bereik als argument vereisen, zoals GetValue, GetFormula, ClearAll, enz.


Activate

Als het argument bladnaam wordt opgegeven, wordt het opgegeven blad geactiveerd en wordt het het momenteel geselecteerde blad. Als het argument ontbreekt, wordt het documentvenster geactiveerd.

Syntaxis:

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

Parameters:

bladnaam: de naam van het blad dat in het document moet worden geactiveerd. De standaardwaarde is een lege tekenreeks, wat betekent dat het documentvenster wordt geactiveerd zonder het actieve blad te wijzigen.

Voorbeeld:

Het onderstaande voorbeeld activeert het blad met de naam "Blad4" in het huidige actieve document.

In BASIC

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

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

Het activeren van een werkblad heeft alleen zin als het wordt uitgevoerd op een Calc-document. Om er zeker van te zijn dat u een Calc-document bij de hand heeft, kunt u de eigenschap isCalc van het documentobject gebruiken, dat True retourneert als het een Calc-document is en anders False.


Charts

Retourneert ofwel de lijst met de namen van alle grafiekobjecten in een bepaald blad of een enkele service-instantie Chart.

Syntaxis:

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

Parameters:

bladnaam: De naam van het blad waaruit de lijst met grafieken moet worden opgehaald of waar de opgegeven grafiek zich bevindt.

kaartnaam: de door de gebruiker gedefinieerde naam van het kaartobject dat moet worden geretourneerd. Als de kaart geen door de gebruiker gedefinieerde naam heeft, kan de interne objectnaam worden gebruikt. Als dit argument ontbreekt, wordt de lijst met diagramnamen in het opgegeven blad geretourneerd.

tip

Gebruik de zijbalk Navigator om de namen te controleren die zijn toegewezen aan kaarten onder de categorie OLE-objecten.


Voorbeeld:

In BASIC

Het onderstaande voorbeeld toont het aantal grafiekobjecten in "Blad1".


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

Het volgende voorbeeld geeft toegang tot de grafiek met de naam "MyChart" in "Blad1" en drukt het type ervan af.


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

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

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

ClearAll

Wist alle inhoud en formaten van het opgegeven bereik.

Syntaxis:

svc.ClearAll(range: str)

Parameters:

bereik: het bereik dat moet worden gewist, als een tekenreeks.

Voorbeeld:

In BASIC

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

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

ClearFormats

Wist de formaten en opmaakprofielen in het opgegeven bereik.

Syntaxis:

svc.ClearFormats(range: str)

Parameters:

bereik: het bereik waarvan de formaten en stijlen moeten worden gewist, als een tekenreeks.

Voorbeeld:

In BASIC

      oDoc.ClearFormats("SheetX.*")
  
In Python

    myDoc.ClearFormats("SheetX.*")
  

ClearValues

Wist de waarden en formules in het opgegeven bereik.

Syntaxis:

svc.ClearValues(range: str)

Parameters:

bereik: het bereik waarvan de waarden en formules moeten worden gewist, als een tekenreeks.

Voorbeeld:

In BASIC

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

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

CompactLeft

Verwijdert de kolommen van een opgegeven bereik die overeenkomen met een filter uitgedrukt als een Calc-formule. Het filter wordt toegepast op elke kolom om te beslissen of deze zal worden verwijderd of niet.

De verwijderde kolom kan worden beperkt tot de hoogte van het opgegeven bereik of tot de hoogte van het hele blad, waardoor hele kolommen worden verwijderd.

Deze methode retourneert een tekenreeks met het bereikadres van het gecomprimeerde bereik. Als alle kolommen worden verwijderd, wordt een lege tekenreeks geretourneerd.

note

Als een celbereik is geselecteerd, heeft het aanroepen van deze methode geen invloed op de selectie.


Syntaxis:

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

Parameters:

bereik: het bereik waaruit kolommen worden verwijderd, als een tekenreeks.

wholecolumn: als deze optie is ingesteld op True wordt de hele kolom van het blad verwijderd. De standaardwaarde is False, wat betekent dat de verwijderde kolom wordt beperkt tot de hoogte van het opgegeven bereik.

filterformule: het filter dat op elke kolom moet worden toegepast om te bepalen of deze al dan niet wordt verwijderd. Het filter wordt uitgedrukt als een Calc-formule die op de eerste kolom moet worden toegepast. Wanneer de formule True retourneert voor een kolom, wordt die kolom verwijderd. Het standaardfilter verwijdert alle lege kolommen.

Stel bijvoorbeeld dat het bereik A1:J200 is geselecteerd (hoogte = 200), dus de standaardformule is =(AANTAL.LEGE.CELLEN(A1:A200)=200). Dit betekent dat als alle 200 cellen leeg zijn in de eerste kolom (A), de kolom wordt verwijderd. Merk op dat de formule alleen wordt uitgedrukt met betrekking tot de eerste kolom. Intern zal de CompactLeft methode deze formule generaliseren voor alle overige kolommen.

Voorbeeld:

In BASIC

    ' Verwijder alle lege kolommen in het bereik G1:L10 van Blad1
    newrange = oDoc.CompactLeft("Blad1.G1:L10")
    ' Het onderstaande voorbeeld is vergelijkbaar, maar de hele kolom is verwijderd uit het blad
    newrange = oDoc.CompactLeft("Blad1.G1:L10", WholeColumn := True)
    ' Verwijdert alle kolommen waarvan de eerste rij is gemarkeerd met een "X"
    newrange = oDoc.CompactLeft("Blad1.G1:L10", FilterFormula := "=(G1=""X"")")
    ' Verwijdert alle kolommen waarvan de som van de waarden in de kolom oneven is
    newrange = oDoc.CompactLeft("Blad1.G1:L10", FilterFormula := "=(MOD(SUM(G1:G10);2)=1)")
  
In Python

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

CompactUp

Verwijdert de rijen van een opgegeven bereik die overeenkomen met een filter uitgedrukt als een Calc-formule. Het filter wordt toegepast op elke rij om te beslissen of deze wordt verwijderd of niet.

De verwijderde rijen kunnen worden beperkt tot de breedte van het opgegeven bereik of overspannen tot de breedte van het hele blad, waardoor hele rijen worden verwijderd.

Deze methode retourneert een tekenreeks met het bereikadres van het gecomprimeerde bereik. Als alle rijen zijn verwijderd, wordt een lege tekenreeks geretourneerd.

note

Als een celbereik is geselecteerd, heeft het aanroepen van deze methode geen invloed op de selectie.


Syntaxis:

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

Parameters:

range: het bereik waaruit rijen worden verwijderd, als een tekenreeks.

wholerow: als deze optie is ingesteld op True wordt de hele rij van het blad verwijderd. De standaardwaarde is False, wat betekent dat de verwijderde rij wordt beperkt tot de breedte van het opgegeven range.

filterformula: het filter dat op elke rij moet worden toegepast om te bepalen of deze al dan niet wordt verwijderd. Het filter wordt uitgedrukt als een Calc-formule die op de eerste rij moet worden toegepast. Wanneer de formule True retourneert voor een rij, wordt die rij verwijderd. Het standaardfilter verwijdert alle lege rijen.

Stel bijvoorbeeld dat het bereik A1:J200 is geselecteerd (breedte = 10), dus de standaardformule is =(AANTAL.LEGE.CELLEN(A1:J1)=10). Dit betekent dat als alle 10 cellen leeg zijn in de eerste rij (rij 1), de rij wordt verwijderd. Merk op dat de formule alleen wordt uitgedrukt met betrekking tot de eerste rij. Intern zal de CompactUp methode deze formule generaliseren voor alle overige rijen.

Voorbeeld:

In BASIC

    ' Verwijder alle lege rijen in het bereik G1:L10 uit Blad1
    newrange = oDoc.CompactUp("Blad1.G1:L10")
    ' Het onderstaande voorbeeld is vergelijkbaar, maar de hele rij is verwijderd uit het blad
    newrange = oDoc.CompactUp("Blad1.G1:L10", WholeRow := True)
    ' Verwijdert alle rijen waarvan de eerste kolom is gemarkeerd met een "X"
    newrange = oDoc.CompactUp("Blad1.G1:L10", FilterFormula := "=(G1=""X"")")
    ' Verwijdert alle rijen waarvan de som van de waarden in de rij oneven is
    newrange = oDoc.CompactUp("Blad1.G1:L10", FilterFormula := "=(MOD(SUM(G1:L1);2)=1)")
  
In Python

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

CopySheet

Kopieert een opgegeven blad vóór een bestaand blad of aan het einde van de lijst met bladen. Het te kopiëren blad kan zich in elk open Calc-document bevinden. Retourneert True indien succesvol.

Syntaxis:

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

Parameters:

sheetname: de naam van het blad dat moet worden gekopieerd als een tekenreeks of de referentie ervan als een object.

newname: De naam van het blad dat moet worden ingevoegd. De naam mag niet in gebruik zijn in het document.

beforesheet: De naam (tekenreeks) of index (numeriek, beginnend bij 1) van het blad waarvoor het gekopieerde blad moet worden ingevoegd. Dit argument is optioneel en het standaardgedrag is om het gekopieerde blad op de laatste positie toe te voegen.

Voorbeeld:

In BASIC

Het volgende voorbeeld maakt een kopie van het blad "BladX" en plaatst dit als het laatste blad in het huidige document. De naam van het gekopieerde blad is "BladY".


    Dim oDoc as Object
    'Haalt het Document-object van het actieve venster'
    Set oDoc = CreateScriptService("Calc")
    oDoc.CopySheet("SheetX", "SheetY")
  

Het onderstaande voorbeeld kopieert "BladX" van "File.ods" en plakt het op de laatste positie van "FileB.ods" met de naam "BladY":


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

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

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

Om werkbladen tussen open documenten te kopiƫren, gebruik CopySheet. Om werkbladen tussen gesloten documenten te kopiƫren, gebruik CopySheetFromFile.


CopySheetFromFile

Kopieert een gespecificeerd blad van een gesloten Calc-document en plakt het voor een bestaand blad of aan het einde van de lijst met bladen van het bestand waarnaar wordt verwezen door een Document-object.

Als het bestand niet bestaat, wordt er een fout gegenereerd. Als het bestand geen geldig Calc-bestand is, wordt een leeg blad ingevoegd. Als het bronblad niet bestaat in het invoerbestand, wordt een foutmelding bovenaan het nieuw geplakte blad ingevoegd.

Syntaxis:

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

Parameters:

bestandsnaam: identificeert het te openen bestand. Het moet de notatie SF_FileSystem.FileNaming volgen. Het bestand mag niet worden beveiligd met een wachtwoord.

sheetname: De naam van het blad dat als tekenreeks moet worden gekopieerd.

newname: De naam van het gekopieerde blad dat in het document moet worden ingevoegd. De naam mag niet in gebruik zijn in het document.

beforesheet: De naam (tekenreeks) of index (numeriek, beginnend bij 1) van het blad waarvoor het gekopieerde blad moet worden ingevoegd. Dit argument is optioneel en het standaardgedrag is om het gekopieerde blad op de laatste positie toe te voegen.

Voorbeeld:

Het volgende voorbeeld kopieert "BladX" van "myFile.ods" en plakt het op de eerste positie in het document waarnaar wordt verwezen door "oDoc" als "BladY".

In BASIC

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

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

CopyToCell

Kopieert een opgegeven bronbereik (waarden, formules en indelingen) naar een doelbereik of cel. De methode reproduceert het gedrag van een kopieer-/plakbewerking van een bereik naar een enkele cel.

Het retourneert een tekenreeks die het gewijzigde celbereik vertegenwoordigt. De grootte van het gewijzigde gebied wordt volledig bepaald door de grootte van het brongebied.

Het bronbereik kan bij een ander geopend document horen.

Syntaxis:

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

Parameters:

sourcerange: Het bronbereik als tekenreeks als het bij hetzelfde document hoort of als verwijzing als het bij een ander geopend Calc-document hoort.

destinationcell: De doelcel waar het gekopieerde celbereik wordt geplakt, als een tekenreeks. Als een bereik is opgegeven, wordt alleen de cel linksboven in aanmerking genomen.

Voorbeeld:

In BASIC

Hierna volgt een voorbeeld waarbij de bron en het doel zich in hetzelfde bestand bevinden:


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

Het onderstaande voorbeeld illustreert hoe u een bereik kopieert uit een ander geopend Calc-document:


    Dim ui as Variant : ui = CreateScriptService("UI")
    Dim oDocSource As Object, oDocDestination As Object
    'Open het brondocument op de achtergrond (verborgen)
    Set oDocSource = ui.OpenDocument("C:\SourceFile.ods", Hidden := True, ReadOnly := True)
    Set oDocDestination = CreateScriptService("Calc")
    oDocDestination.CopyToCell(oDocSource.Range("Sheet1.C2:C4"), "SheetT.A5")
    'Vergeet niet het brondocument te sluiten, omdat het als verborgen werd geopend
    oDocSource.CloseDocument()
  
In Python

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

Gebruik CopyToCell om kopiƫren/plakken van een bereik naar een enkele cel te simuleren. Gebruik CopyToRange om kopiƫren/plakken van een bereik naar een groter bereik te simuleren (waarbij dezelfde cellen meerdere keren worden gerepliceerd).


CopyToRange

Kopieert naar beneden en/of naar rechts een gespecificeerd bronbereik (waarden, formules en formaten) naar een doelbereik. De methode imiteert het gedrag van een kopieer-/plakbewerking van een bronbereik naar een groter doelbereik.

De methode retourneert een tekenreeks die het gewijzigde celbereik vertegenwoordigt.

Het bronbereik kan bij een ander geopend document horen.

Syntaxis:

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

Parameters:

sourcerange: Het bronbereik als tekenreeks als het bij hetzelfde document hoort of als verwijzing als het bij een ander geopend Calc-document hoort.

destinationrange: De bestemming van het gekopieerde celbereik, als een tekenreeks.

Voorbeeld:

In BASIC

Kopieer binnen hetzelfde document:


    oDoc.CopyToRange("SheetX.A1:F10", "SheetY.C5:J5")
    ' Retourneert een bereiktekenreeks: "$SheetY.$C$5:$J$14"
  

Kopieer van het ene bestand naar het andere:


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

    doc.CopyToRange("SheetX.A1:F10", "SheetY.C5:J5")
  

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

CreateChart

Maakt een nieuw grafiekobject met de gegevens in het opgegeven bereik. Het geretourneerde kaartobject kan verder worden gemanipuleerd met behulp van de service Chart.

Syntaxis:

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

Parameters:

chartname: De door de gebruiker gedefinieerde naam van de te maken grafiek. De naam moet uniek zijn in hetzelfde blad.

sheetname: De naam van het blad waar de grafiek zal worden geplaatst.

range: Het bereik dat als gegevensbron voor de grafiek moet worden gebruikt. Het bereik kan verwijzen naar elk blad van het Calc-document.

columnheader: Als True, zal de bovenste rij van het bereik worden gebruikt als labels voor de categorie-as of de legenda (Standaard = False).

rowheader: Als True, zal de meest linkse kolom van het bereik worden gebruikt als labels voor de categorie-as of de legenda. (Standaard = False).

Voorbeeld:

In de onderstaande voorbeelden wordt in Basic en in Python een diagram aangemaakt met de gegevens die in de cellen "A1:B5" van "Sheet1" staan, de diagram wordt in "Sheet2" gezet.

In BASIC

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

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

Lees de helppagina over de ScriptForge service Chart voor meer informatie over de mogelijkheden met diagram-objecten .U kunt het diagramtype wijzigen, de diagram, de assen, de titels en de positie.


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.

Syntaxis:

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

Parameters:

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)

Voorbeeld:

In BASIC

    Dim vData As Variant, oDoc As Object, ui As Object, sTable As String, sPivot As String
    Set ui = CreateScriptService("UI")
    Set oDoc = ui.CreateDocument("Calc")
    vData = Array(Array("Item", "State", "Team", "2002", "2003", "2004"), _
        Array("Books", "Michigan", "Jean", 14788, 30222, 23490), _
        Array("Candy", "Michigan", "Jean", 26388, 15641, 32849), _
        Array("Pens", "Michigan", "Jean", 16569, 32675, 25396), _
        Array("Books", "Michigan", "Volker", 21961, 21242, 29009), _
        Array("Candy", "Michigan", "Volker", 26142, 22407, 32841))
    sTable = oDoc.SetArray("A1", vData)
    sPivot = oDoc.CreatePivotTable("PT1", sTable, "H1", _
        Array("2002", "2003;count", "2004;average"), _ ' Three data fields
        "Item", _ ' A single row field
        Array("State", "Team"), False) ' Two column fields
  
In Python

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

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


DAvg, DCount, DMax, DMin and DSum

De functies Average, Count, Max, Min en Sum kunnen gebruikt worden voor alle cellen die een numerieke waarde bevatten binnen een aangegeven bereik.

Syntaxis:

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

Parameters:

range: Een tekenreeks, die het bereik van de cellen aangeeft waarop de functie werkt.

Voorbeeld:

In onderstaand voorbeeld wordt de functie Som uitgevoerd op het bereik "A1:A1000" van het geselecteerde werkblad:

In BASIC

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

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

Cellen in het aangegeven bereik die tekst bevatten worden door deze functies overgeslagen. De methode DCount zal alleen cellen met numerieke inhoud tellen en de cellen met tekst overslaan.


Forms

Afhankelijk van de parameters retourneert deze methode:

Syntaxis:

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

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

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

Parameters:

sheetname: De naam van het werkblad, als een tekenreeks, waar het form van wordt opgehaald.

form: De naam of index van een form op een aangegeven werkblad. Indien het argument ontbreekt zal de methode een lijst met alle beschikbare forms op het werkblad retourneren.

Voorbeeld:

In de volgende voorbeelden wordt met de eerste regel steeds de namen van alle forms op het werkblad "Sheet1" opgehaald, in de volgende regel wordt het object Form van het form "Form_A" opgehaald. "Form_A" is de naam van een form op werkblad "Sheet1".

In BASIC

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

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

GetColumnName

Converteert een kolomnummer in het bereik 1-1024 naar de overeenkomende letter (kolom 'A', 'B', ..., 'AMJ'). Als het kolomnummer buiten het bereik ligt, dan wordt er een lege tekenreeks geretourneerd.

Syntaxis:

svc.GetColumnName(columnnumber: int): str

Parameters:

columnnumber: Het kolomnummer als een geheel getal in het bereik 1 ... 1024.

Voorbeeld:

In BASIC

Toont een berichtvenster met de naam van de derde kolom, standaard is dat "C".


    MsgBox oDoc.GetColumnName(3)
  
In Python

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

Het maximale aantal kolommen in een Calc-werkblad is 1024.


GetFormula

Haalt de formule(s) op in het aangegeven bereik van cellen als een enkele tekenreeks, een 1D of een 2D matrix van tekenreeksen.

Syntaxis:

svc.GetFormula(range: str): any

Parameters:

range: Het bereik van cellen waar de formules van opgehaald moeten worden.

Voorbeeld:

In BASIC

In dit voorbeeld wordt een 3 bij 2 matrix geretourneerd, omdat in het bereik "A1:B3" 3 rijen (cijfers) en 2 kolommen (letters) zitten:


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

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

GetValue

Haalt de waarde(n) in het gegeven bereik op als een enkele waarde, een 1D matrix of een 2D matrix. Elke waarde is een ''double' of een 'string'.

Syntaxis:

svc.GetValue(range: str): any

Parameters:

range: Het bereik waar de waarden van opgehaald moet worden, als een tekenreeks.

Voorbeeld:

In BASIC

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

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

Als een cel een datum bevat, wordt het getal dat daarmee overeenkomt geretourneerd. Om in een Basic-script een getal te converteren naar een datum, gebruik de Basic functie CDate. In Python-scripts, gebruik de functie CDate van de service Basic.


ImportFromCSVFile

Importeert de inhoud van een CSV-bestand en plaatst het in een aangegeven cel.

De inhoud en opmaak van deze aangegeven cel wordt hierbij gewist. De grootte van de cel is afhankelijk van de inhoud van het invoerbestand.

Deze methode retourneert een tekenreeks die staat voor het bereik van de gewijzigde cellen.

Syntaxis:

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

Parameters:

filename: Geeft het te openen bestand aan. De notatie moet voldoen aan de normen van SF_FileSystem.FileNaming.

destinationcell: De cel waarin de inhoud van het bestand als een tekenreeks wordt geplaatst. Als hier een bereik wordt opgegeven, dan is de cel die gebruikt wordt, de cel linksboven in het bereik.

filteroptions: De argumenten voor het CSV-invoerfilter. Bij het standaardfilter worden de volgende aannames gedaan:

Voorbeeld:

In BASIC

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

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

Meer informatie over CSV filteropties.


ImportFromDatabase

Importeert de inhoud dan een database-tabel, query of het resultaat van een SQL-commando, bijvoorbeeld een SELECT, dat in de cel 'destination' wordt geplaatst.

Het bereik van cellen waar het resultaat wordt geplaatst wordt eerst geleegd wat de inhoud en de opmaak betreft. Het aantal cellen dat hierbij gebruikt wordt is volledig afhankelijk van de inhoud van de tabel of de query.

De methode retourneert True wanneer het importeren lukt.

Syntaxis:

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

Parameters:

filename: Geeft het te openen bestand aan. De notatie moet voldoen aan de normen van SF_FileSystem.FileNaming.

registrationname: De naam die gebruikt moet worden om de database te vinden in het databases register. Dit argument wordt genegeerd als er een filename wordt meegegeven.

destinationcell: De bestemming van de geĆÆmporteerde gegevens. Als er een bereik wordt opgegeven, dan wordt alleen de cel linksboven gebruikt.

sqlcommand: Een tabelnaam , een query-naam (zonder de omringende aanhalingstekens of vierkante haken) of een SELECT SQL-statement (waarbij de tabelnaam en de veldnamen omringt mogen worden met aanhalingstekens of vierkante haken, dit om de leesbaarheid te verbeteren).

directsql: Indien True, het SQL-commando wordt direct naar de database engine gestuurd zonder eerst geanalyseerd te worden. De standaardwaarde is False. Het argument wordt bij tabellen genegeerd. Bij queries, de gebruikte optie is de optie die gebruikt is bij de definitie van de query.

Voorbeeld:

In BASIC

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

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

InsertSheet

Voegt een leeg tabblad toe voor een bestaand tabblad of aan het eind.

Syntaxis:

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

Parameters:

sheetname: De naam van het nieuwe tabblad.

beforesheet: De naam (tekenreeks) of index (numeriek, beginnend met 1) van het tabblad waar het nieuwe tabblad voor moet worden toegevoegd. Dit argument is optioneel, standaard wordt een nieuw tabblad achteraan toegevoegd.

Voorbeeld:

In dit voorbeeld wordt een tabblad "SheetX" toegevoegd voor tabblad "SheetY":

In BASIC

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

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

MoveRange

Verplaatst een aangegeven bronbereik naar bestemmingsbereik van cellen. De methode retourneert een tekenreeks die het gewijzigde bereik van cellen aangeeft. De omvang van het gewijzigde gebied wordt volledig bepaald door de grootte van het bronbereik.

Syntaxis:

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

Parameters:

source: Het bronbereik van de cellen, als een tekenreeks.

destination: De cel waar de gegevens in worden gezet, als een tekenreeks. Als hier een bereik wordt opgegeven, dan is de cel die gebruikt wordt, de cel linksboven in het bereik.

Voorbeeld:

In BASIC

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

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

MoveSheet

Verplaatst een bestaand tabblad en plaatst het voor een aangegeven tabblad of aan het eind.

Syntaxis:

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

Parameters:

sheetname: De naam van het te verplaatsen tabblad. Het tabblad moet bestaan.

beforesheet: De naam (tekenreeks) of index (numeriek, beginnen met 1) van het tabblad waar het originele tabblad voor moet worden geplaatst. Dit argument is optioneel, standaard wordt het tabblad achteraan geplaatst.

Voorbeeld:

Dit voorbeeld verplaatst het tabblad "SheetX" naar de plek voor tabblad "SheetY":

In BASIC

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

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

Offset

Retourneert een nieuw bereik (als een tekenreeks) offset bij een bepaald aantal rijen en kolommen van een gegeven bereik.

Deze methode is gelijkwaardig aan de Calc-functie Offset.

Syntaxis:

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

Parameters:

reference: Het bereik, als een tekenreeks, dat de methode zal gebruiken als referentie voor het uitvoeren van de instructie offset.

rows: Het aantal rijen waar het initiƫle bereik is offset naar boven (negatieve waarde) of naar beneden (positieve waarde). Gebruik 0 (standaard) om in dezelfde rij te blijven.

columns: Het aantal kolommen waar het initiƫle bereik is offset naar links (negatieve waarde) of naar rechts (positieve waarde). Gebruik 0 (standaard) om in dezelfde kolom te blijven.

height: De verticale hoogte voor een gebied dat begint op de positie van het nieuwe bereik. Laat dit argument weg als er geen verticale aanpassing nodig is.

width: De horizontale breedte voor een gebied dat begint op de positie van het nieuwe bereik. Laat dit argument weg als er geen horizontale aanpassing nodig is.

Argumenten rows en columns moeten niet betekenen dat de startrij of startkolom kleiner wordt dan 1.

Argumenten height en width moeten niet betekenen dat het aantal kolommen of rijen lager wordt dan 1.

Voorbeeld:

In BASIC

    oDoc.Offset("A1", 2, 2)
    'SheetX.$C$3 (A1 twee rijen naar rechts en twee kolommen naar beneden verplaatst)
    oDoc.Offset("A1", 2, 2, 5, 6)
    'SheetX.$C$3:$H$7 (A1 offset van 2 rijen en kolommen en met een breedte van 5 rijen en 5 kolommen)
  
In Python

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

OpenRangeSelector

Opent een 'non-modal' dialoogvenster dat gebruikt kan worden om een bereik in het document te selecteren, het retourneert een tekenreeks met het geselecteerde bereik.

note

Deze methode opent hetzelfde dialoogvenster dat gebruikt wordt door LibreOfficeDev wanneer de knop Verkleinen wordt ingedrukt. Het dialoogvenster Extra - Doel zoeken heeft bijvoorbeeld die knop rechts naast het veld Formulecel.


Deze methode wijzigt de huidige selectie niet.

Syntaxis:

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

Parameters:

title: De titel van het dialoogvenster, als een tekenreeks.

selection: Een optioneel bereik dat al is geselecteerd bij het tonen van het dialoogvenster.

singlecell: Bij True (standaard) is alleen selectie van ƩƩn cel toegestaan.Bij False is selectie van een bereik toegestaan.

closeafterselect: Bij True (standaard) wordt het dialoogvenster direct gesloten nadat de selectie is gemaakt. Bij False kan de gebruiker de selectie een aantal keer heroverwegen en na selectie zelf het dialoogvenster sluiten.

Voorbeeld:

In BASIC

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

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

Printf

Returns the input string after substituting its token characters by their values in a given range.

This method does not change the current selection.

tip

This method can be used to quickly extract specific parts of a range name, such as the sheet name or first cell column and row, and use them to compose a new range address.


Syntaxis:

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

Parameters:

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:

Voorbeeld:

In 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))
  
In Python

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

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

PrintOut

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.

Syntaxis:

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

Parameters:

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.

Voorbeeld:

In BASIC

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

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

RemoveSheet

Removes an existing sheet from the document.

Syntaxis:

svc.RemoveSheet(sheetname: str): bool

Parameters:

sheetname: The name of the sheet to remove.

Voorbeeld:

In BASIC

    oDoc.RemoveSheet("SheetY")
  
In Python

    myDoc.RemoveSheet("SheetY")
  

RenameSheet

Renames the given sheet and returns True if successful.

Syntaxis:

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

Parameters:

sheetname: The name of the sheet to rename.

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

Voorbeeld:

This example renames the active sheet to "SheetY":

In BASIC

    oDoc.RenameSheet("~", "SheetY")
  
In 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.

Syntaxis:

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

Parameters:

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.

Voorbeeld:

In 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))
  
In Python

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

    myDoc.SetArray("Sheet1.A1", tuple(i + 1 for i in range(1000)))
  
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.

Syntaxis:

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

Parameters:

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.

Voorbeeld:

In 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)
  
In Python

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

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

SetCellStyle

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.

Syntaxis:

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

Parameters:

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

style: The name of the cell style to apply.

Voorbeeld:

In BASIC

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

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

SetFormula

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.

Syntaxis:

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

Parameters:

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.

Voorbeeld:

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

note

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


Syntaxis:

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

Parameters:

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.

Voorbeeld:

In 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
  
In Python

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

ShiftLeft

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.

Syntaxis:

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

Parameters:

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.

Voorbeeld:

In 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)
  
In 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.

Syntaxis:

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

Parameters:

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.

Voorbeeld:

In 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)
  
In 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.

note

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


Syntaxis:

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

Parameters:

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.

Voorbeeld:

In 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)
  
In 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.

Syntaxis:

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

Parameters:

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 : Alleen voor het vergelijken van teksten. Standaardwaarde is False.

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

Voorbeeld:

In BASIC

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

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

Alle ScriptForge Basic-routines of variabelen die beginnen met een underscore "_" zijn voor intern gebruik. Gebruik deze niet in een Basic of Python-macro.