Dienst SFDocuments.Calc

Die Bibliothek SFDocuments bietet eine Reihe von Methoden und Eigenschaften, um die Verwaltung und Handhabung von LibreOffice Calc-Dokumenten zu erleichtern.

Einige Methoden sind generisch für alle Arten von Dokumenten und werden vom Dienst Document geerbt, während andere Methoden spezifisch für das Modul SF_Calc sind.

Das Modul SF_Calc konzentriert sich auf:

Dienstaufruf

Der Dienst Calc ist eng verwandt mit dem Dienst UI der Bibliothek ScriptForge. Nachfolgend finden Sie einige Beispiele, wie der Dienst Calc aufgerufen werden kann.

In Basic

Der folgende Code-Schnipsel erstellt eine Dienstinstanz Calc, die dem derzeit aktiven Calc-Dokument entspricht.


    Set oDoc = CreateScriptService("Calc")
  

Eine andere Möglichkeit, eine Instanz des Dienstes Calc zu erstellen, ist die Verwendung des Dienstes UI. Im folgenden Beispiel wird ein neues Calc-Dokument erstellt und oDoc ist eine Dienstinstanz Calc:


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

Oder verwenden Sie die Methode OpenDocument des Dienstes UI:


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

Es ist auch möglich, den Dienst Calc mit der Methode CreateScriptService zu instanziieren:


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

Im obigen Beispiel ist "MyFile.ods" der Name eines geöffneten Dokumentfensters. Wenn dieses Argument nicht angegeben wird, wird das aktive Fenster berücksichtigt.

Es wird empfohlen, Ressourcen nach der Verwendung freizugeben:


    Set oDoc = oDoc.Dispose()
  

Wenn das Dokument jedoch mit der Methode CloseDocument geschlossen wurde, ist es unnötig, Ressourcen mit dem oben beschriebenen Befehl freizugeben.

In Python

    myDoc = CreateScriptService("Calc")
  

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

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

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

Die Verwendung des Präfixes "SFDocuments." beim Aufruf des Dienstes ist optional.


Definitionen

Viele Methoden benötigen ein "Sheet" oder einen "Range" als Argument. Einzelne Zellen werden als Sonderfall eines Range betrachtet.

Beide können je nach Situation entweder als Zeichenfolge oder als Referenz (= Objekt) ausgedrückt werden:

Beispiel:

Im folgenden Beispiel werden Daten aus Dokument A (schreibgeschützt geöffnet und ausgeblendet) in Dokument B kopiert.

In Basic

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

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

SheetName

Entweder der Tabellenname als Zeichenfolge oder ein Objekt, das von der Eigenschaft .Sheet erzeugt wird.

Das Kürzel "~" (Tilde) repräsentiert die aktuelle Tabelle.

RangeName

Entweder eine Zeichenfolge, die einen Satz zusammenhängender Zellen bezeichnet, die sich in einer Tabelle der aktuellen Instanz befinden, oder ein Objekt, das von der Eigenschaft .Range erzeugt wird.

Das Kürzel „~“ (Tilde) repräsentiert die aktuelle Auswahl oder den ersten ausgewählten Bereich, wenn mehrere Bereiche ausgewählt sind.

Das Kürzel "*" repräsentiert alle verwendeten Zellen.

Der Tabellenname ist optional in einem Bereich (Standard = die aktive Tabelle). Umgebende einfache Anführungszeichen und Zeichen $ sind erlaubt, werden aber ignoriert.

tip

Mit Ausnahme der Eigenschaft CurrentSelection berücksichtigt der Dienst Calc nur einzelne Zellbereiche.


Beispiele für gültige Bereiche

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

Eine einzelne Zelle

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

Einzelner Bereich mit mehreren Zellen

'$TabelleX'.*

Alle verwendeten Zellen in der angegebenen Tabelle

1) '$TabelleX'.A:A (Spalte A)
2) 3:5 (Zeilen 3 bis 5)

Alle Zellen in zusammenhängenden Spalten oder Zeilen bis zur letzten verwendeten Zelle

MeinBereich

Ein Bereich mit dem Namen "MeinBereich" auf Tabellenebene

1) ~.einBereich
2) SheetX.einBereich

Ein Bereichsname auf Tabellenebene

MyDoc.Range("TabelleX.D2:F6")

Ein Bereich innerhalb der Tabelle „TabelleX“ in der Datei, die der Calc-Instanz "myDoc" zugeordnet ist

~.~ oder ~

Die aktuelle Auswahl in der aktiven Tabelle


Eigenschaften

Alle Eigenschaften, die generisch für jedes Dokument sind, gelten implizit auch für Calc-Dokumente. Weitere Informationen finden Sie auf der Dokumentendienst-Hilfeseite.

Die speziell für Calc-Dokumente verfügbaren Eigenschaften sind:

Name

ReadOnly

Argument

Typ

Beschreibung

CurrentSelection

Nein

Ohne

Zeichenfolge oder Matrix mit Zeichenfolgen

Der einzelne ausgewählte Bereich als Zeichenfolge oder die Liste der ausgewählten Bereiche als Matrix

Height

Ja

RangeName As String

Long

Die Anzahl der Zeilen (>= 1) im angegebenen Bereich

LastCell

Ja

SheetName As String

String

Die letzte verwendete Zelle im Format 'A1' in der angegebenen Tabelle

LastColumn

Ja

SheetName As String

Long

Die zuletzt verwendete Spalte in der angegebenen Tabelle

LastRow

Ja

SheetName As String

Long

Die letzte verwendete Zeile in der angegebenen Tabelle

Range

Ja

RangeName As String

Object

Eine Bereichsreferenz, die als Argument von Methoden wie CopyToRange verwendet werden kann

Sheet

Ja

SheetName As String

Object

Eine Tabellenreferenz, die als Argument von Methoden wie CopySheet verwendet werden kann

Sheets

Ja

Ohne

Matrix mit Zeichenfolgen

Die Liste mit den Namen aller vorhandenen Tabellen

Width

Ja

RangeName As String

Long

Die Anzahl der Spalten (>= 1) im angegebenen Bereich

XCellRange

Ja

RangeName As String

Object

Ein UNO-Objekt com.sun.star.Table.XCellRange

XSpreadsheet

Ja

SheetName As String

Object

Ein UNO-Objekt com.sun.star.Table.XCellRange


tip

Besuchen Sie die Website der LibreOffice-API-Dokumentation, um mehr über dir UNO-Objekte XCellRange und XSpreadsheet zu lernen.


Methoden

Liste der Methoden im Dienst Calc

Activate
ClearAll
ClearFormats
ClearValues
CopySheet
CopySheetFromFile
CopyToCell
CopyToRange
DAvg
DCount

DMax
DMin
DSum
Forms
GetColumnName
GetFormula
GetValue
ImportFromCSVFile
ImportFromDatabase
InsertSheet

MoveRange
MoveSheet
Offset
RemoveSheet
RenameSheet
SetArray
SetValue
SetCellStyle
SetFormula
SortRange


Activate

Wenn das Argument SheetName angegeben wird, wird die angegebene Tabelle aktiviert und zur aktuell ausgewählten Tabelle. Wenn das Argument fehlt, wird das Dokumentfenster aktiviert.

Syntax:

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

Parameter:

sheetname: Der Name der Tabelle, die im Dokument aktiviert werden soll. Der Standardwert ist eine leere Zeichenfolge, was bedeutet, dass das Dokumentfenster aktiviert wird, ohne die aktive Tabelle zu ändern.

Beispiel:

Das folgende Beispiel aktiviert die Tabelle mit dem Namen "Sheet4" im derzeit aktiven Dokument.

In Basic

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

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

Das Aktivieren einer Tabelle ist nur sinnvoll, wenn es auf einem Calc-Dokument durchgeführt wird. Um sicherzustellen, dass Sie ein Calc-Dokument zur Hand haben, können Sie die Eigenschaft isCalc des Dokumentobjekts verwenden, die True zurückgibt, wenn es sich um ein Calc-Dokument handelt, und False andernfalls.


ClearAll

Löscht alle Inhalte und Formate des angegebenen Bereichs.

Syntax:

svc.ClearAll(range: str)

Parameter:

range: Der zu löschende Bereich als Zeichenfolge.

Beispiel:

In Basic

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

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

ClearFormats

Löscht die Formate und Vorlagen im angegebenen Bereich.

Syntax:

svc.ClearFormats(range: str)

Parameter:

range: Der Bereich, dessen Formate und Vorlagen gelöscht werden sollen, als eine Zeichenfolge.

Beispiel:

In Basic

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

    myDoc.ClearFormats("SheetX.*")
  

ClearValues

Löscht die Werte und Formeln im angegebenen Bereich.

Syntax:

svc.ClearValues(range: str)

Parameter:

range: Der Bereich, dessen Werte und Formeln gelöscht werden sollen, als eine Zeichenfolge.

Beispiel:

In Basic

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

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

CopySheet

Kopiert eine angegebene Tabelle vor eine vorhandene Tabelle oder an das Ende der Tabellenliste. Die zu kopierende Tabelle kann in jedem geöffneten Calc-Dokument enthalten sein. Gibt bei Erfolg True zurück.

Syntax:

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

Parameter:

sheetname: Der Name der zu kopierenden Tabelle als Zeichenfolge oder seine Referenz als Objekt.

newname: Der Name der einzufügenden Tabelle. Der Name darf im Dokument nicht verwendet werden.

beforesheet: Der Name (String) oder Index (numerisch, beginnend mit 1) der Tabelle, vor der die kopierte Tabelle eingefügt werden soll. Dieses Argument ist optional und standardmäßig wird die kopierte Tabelle an der letzten Position hinzugefügt.

Beispiel:

In Basic

Das folgende Beispiel erstellt eine Kopie der TAbelle "SheetX" und platziert sie als letzte Tabelle im aktuellen Dokument. Der Name der kopierten Tabelle ist "SheetY".


    Dim oDoc as Object
    ' Ruft das Objekt "Document" des aktiven Fensters ab
    Set oDoc = CreateScriptService("Calc")
    oDoc.CopySheet("SheetX", "SheetY")
  

Das folgende Beispiel kopiert „SheetS“ aus „File.ods“ und fügt sie an der letzten Position von „FileB.ods“ mit dem Namen „SheetY“ ein:


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

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

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

Um Tabellen zwischen offenen Dokumenten zu kopieren, verwenden Sie CopySheet. Um Tabellen aus geschlossenen Dokumenten zu kopieren, verwenden Sie CopySheetFromFile.


CopySheetFromFile

Kopiert eine bestimmte Tabelle aus einem geschlossenen Calc-Dokument und fügt sie vor einer bestehenden Tabelle oder am Ende der Liste der Tabellen der Datei ein, auf die durch ein Objekt Document verwiesen wird.

Wenn die Datei nicht existiert, wird ein Fehler ausgelöst. Wenn die Datei keine gültige Calc-Datei ist, wird eine leere Tabelle eingefügt. Wenn die Quelltabelle nicht in der Eingabedatei vorhanden ist, wird am Anfang der neu eingefügten Tabelle eine Fehlermeldung eingefügt.

Syntax:

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

Parameter:

filename: Identifiziert die zu öffnende Datei. Es muss der Notation SF_FileSystem.FileNaming folgen. Die Datei darf nicht mit einem Kennwort geschützt sein.

sheetname: Der Name der zu kopierenden Tabelle als eine Zeichenfolge.

newname: Der Name der kopierten Tabelle, die in das Dokument eingefügt werden soll. Der Name darf im Dokument nicht verwendet werden.

beforesheet: Der Name (Zeichenfolge) oder Index (numerisch, beginnend mit 1) der Tabelle, vor der die kopierte Tabelle eingefügt werden soll. Dieses Argument ist optional und standardmäßig wird die kopierte Tabelle an der letzten Position hinzugefügt.

Beispiel:

Das folgende Beispiel kopiert „SheetX“ aus „myFile.ods“ und fügt sie in das von „oDoc“ referenzierte Dokument als „SheetY“ an der ersten Position ein.

In Basic

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

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

CopyToCell

Kopiert einen angegebenen Quellbereich (Werte, Formeln und Formate) in einen Zielbereich oder eine Zielzelle. Die Methode reproduziert das Verhalten eines Kopier-/Einfügevorgangs aus einem Bereich in eine einzelne Zelle.

Gibt eine Zeichenfolge zurück, die den geänderten Zellbereich darstellt. Die Größe des modifizierten Bereichs wird vollständig durch die Größe des Quellbereichs bestimmt.

Der Quellbereich kann zu einem anderen offenen Dokument gehören.

Syntax:

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

Parameter:

sourcerange: Der Quellbereich als Zeichenfolge, wenn er zum selben Dokument gehört, oder als Referenz, wenn er zu einem anderen geöffneten Calc-Dokument gehört.

destinationcell: Die Zielzelle, in die der kopierte Zellbereich als Zeichenfolge eingefügt wird. Wenn ein Bereich angegeben ist, wird nur die obere linke Zelle berücksichtigt.

Beispiel:

In Basic

Als nächstes folgt ein Beispiel, bei dem sich Quelle und Ziel in derselben Datei befinden:


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

Das folgende Beispiel zeigt, wie Sie einen Bereich aus einem anderen geöffneten Calc-Dokument kopieren:


    Dim ui as Variant : ui = CreateScriptService("UI")
    Dim oDocSource As Object, oDocDestination As Object
    ' Quelldokument im Hintergrund öffnen (ausgeblendet)
    Set oDocSource = ui.OpenDocument("C:\SourceFile.ods", Hidden := True, ReadOnly := True)
    Set oDocDestination = CreateScriptService("Calc")
    oDocDestination.CopyToCell(oDocSource.Range("Sheet1.C2:C4"), "SheetT.A5")
    ' Vergessen Sie nicht, das Quelldokument zu schließen, da es versteckt geöffnet wurde
    oDocSource.CloseDocument()
  
In Python

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

Um ein Kopieren/Einfügen aus einem Bereich in eine einzelne Zelle zu simulieren, verwenden Sie CopyToCell. Um ein Kopieren/Einfügen von einem Bereich in einen größeren Bereich zu simulieren (wobei dieselben Zellen mehrmals repliziert werden), verwenden Sie CopyToRange.


CopyToRange

Kopiert einen angegebenen Quellbereich (Werte, Formeln und Formate) nach unten und/oder nach rechts in einen Zielbereich. Das Verfahren ahmt das Verhalten eines Kopier-/Einfügevorgangs von einem Quellbereich in einen größeren Zielbereich nach.

Die Methode gibt eine Zeichenfolge zurück, die den geänderten Zellbereich darstellt.

Der Quellbereich kann zu einem anderen offenen Dokument gehören.

Syntax:

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

Parameter:

sourcerange: Der Quellbereich als Zeichenfolge, wenn er zum selben Dokument gehört, oder als Referenz, wenn er zu einem anderen geöffneten Calc-Dokument gehört.

destinationrange: Das Ziel des kopierten Zellbereichs als Zeichenfolge.

Beispiel:

In Basic

Innerhalb desselben Dokuments kopieren:


    oDoc.CopyToRange("SheetX.A1:F10", "SheetY.C5:J5")
    ' Gibt eine Bereichszeichenfolge zurück: "$SheetY.$C$5:$J$14"
  

Von einer Datei in eine andere kopieren:


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

Wendet die Funktionen "Average", "Count", "Max", "Min" und "Sum" jeweils auf alle Zellen an, die numerische Werte in einem bestimmten Bereich enthalten.

Syntax:

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

Parameter:

range: Der Bereich, auf den die Funktion angewendet wird, als Zeichenfolge.

Beispiel:

Das folgende Beispiel wendet die Funktion Sum auf den Bereich "A1:A1000" der aktuell ausgewählten Tabelle an:

In Basic

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

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

Zellen im angegebenen Bereich, die Text enthalten, werden von all diesen Funktionen ignoriert. Beispielsweise zählt die Methode DCount keine Zellen mit Text, sondern nur numerische Zellen.


Forms

Abhängig von den bereitgestellten Parametern gibt diese Methode Folgendes zurück:

Syntax:

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

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

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

Parameter:

sheetname: Der Name der Tabelle als Zeichenfolge, aus der das Formular abgerufen wird.

form: Der Name oder Index, der einem in der angegebenen Tabelle gespeicherten Formular entspricht. Fehlt dieses Argument, gibt die Methode eine Liste mit den Namen aller in der Tabelle verfügbaren Formulare zurück.

Beispiel:

In den folgenden Beispielen erhält die erste Zeile die Namen aller Formulare, die in „Tabelle1“ gespeichert sind, und die zweite Zeile ruft das Objekt Form des Formulars namens „Formular_A“ ab, das in „Tabelle1“ gespeichert ist.

In Basic

    Set FormNames = oDoc.Forms("Tabelle1")
    Set FormA = oDoc.Forms("Tabelle1", "Formular_A")
  
In Python

    form_names = doc.Forms("Tabelle1")
    form_A = doc.Forms("Tabelle1", "Formular_A")
  

GetColumnName

Konvertiert eine Spaltennummer zwischen 1 und 1024 in den entsprechenden Buchstaben (Spalte 'A', 'B', …, 'AMJ'). Wenn die angegebene Spaltennummer außerhalb des zulässigen Bereichs liegt, wird eine Zeichenfolge der Länge Null zurückgegeben.

Syntax:

svc.GetColumnName(columnnumber: int): str

Parameter:

columnnumber: Die Spaltennummer als ganzzahliger Wert im Intervall 1 … 1024.

Beispiel:

In Basic

Zeigt ein Meldungsfeld mit dem Namen der dritten Spalte an, der standardmäßig "C" ist.


    MsgBox oDoc.GetColumnName(3)
  
In Python

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

Die maximal zulässige Anzahl von Spalten auf einer Rechentabelle beträgt 1024.


GetFormula

Holt sich die Formel(n), die im angegebenen Zellbereich gespeichert sind, als einzelne Zeichenfolge, als ein- oder zweidimensionale Matrix von Zeichenfolgen.

Syntax:

svc.GetFormula(range: str): any

Parameter:

range: Der Bereich, aus dem die Formeln stammen, als Zeichenfolge.

Beispiel:

In Basic

Das folgende Beispiel gibt eine 3x2-Matrix mit den Formeln im Bereich „A1:B3“ (3 Zeilen x 2 Spalten) zurück:


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

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

GetValue

Ruft den/die im angegebenen Zellbereich gespeicherten Wert(e) als Einzelwert, ein- oder zweidimensionale Matrix ab. Alle Werte sind entweder Doubles oder Zeichenfolgen.

Syntax:

svc.GetValue(range: str): any

Parameter:

range: Der Bereich, aus dem die Werte abgerufen werden, als Zeichenfolge.

Beispiel:

In Basic

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

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

Wenn eine Zelle ein Datum enthält, wird die diesem Datum entsprechende Zahl zurückgegeben. Um numerische Werte in Basic-Skripten in Datumsangaben umzuwandeln, verwenden Sie die integrierte Funktion CDate von Basic. Verwenden Sie in Python-Skripten die Funktion CDate aus dem Dienst Basic.


ImportFromCSVFile

Importiert den Inhalt einer CSV-formatierten Textdatei und platziert ihn in einer bestimmten Zielzelle.

Der Zielbereich wird von allen Inhalten und Formaten gelöscht, bevor der Inhalt der CSV-Datei eingefügt wird. Die Größe des modifizierten Bereichs wird vollständig durch den Inhalt der Eingabedatei bestimmt.

Die Methode gibt eine Zeichenfolge zurück, die den geänderten Zellbereich darstellt.

Syntax:

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

Parameter:

filename: Identifiziert die zu öffnende Datei. Sie muss der Notation SF_FileSystem.FileNaming folgen.

destinationcell: Die Zielzelle zum Einfügen der importierten Daten als Zeichenfolge. Wenn stattdessen ein Bereich angegeben wird, wird nur die obere linke Zelle berücksichtigt.

filteroptions: Die Argumente für den CSV-Eingabefilter. Der Standardfilter geht von folgenden Annahmen aus:

Beispiel:

In Basic

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

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

Weitere Informationen zu den CSV-Filteroptionen finden Sie auf der Wiki-Seite „Filter Options“.


ImportFromDatabase

Importiert den Inhalt einer Datenbanktabelle, Abfrage oder Ergebnismenge, das heißt das Ergebnis eines Befehls "SELECT SQL", und fügt es in eine Zielzelle ein.

Der Zielbereich wird vor dem Einfügen der importierten Inhalte von allen Inhalten und Formaten gelöscht. Die Größe des modifizierten Bereichs wird vollständig durch den Inhalt in der Tabelle oder Abfrage bestimmt.

Die Methode gibt True zurück, wenn der Import erfolgreich war.

Syntax:

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

Parameter:

filename: Identifiziert die zu öffnende Datei. Er muss der Notation SF_FileSystem.FileNaming folgen.

registrationname: Der Name, der verwendet werden soll, um die Datenbank im Datenbankregister zu finden. Dieses Argument wird ignoriert, wenn filename angegeben wird.

destinationcell: Das Ziel der importierten Daten als Zeichenfolge. Wenn ein Bereich angegeben ist, wird nur die obere linke Zelle berücksichtigt.

sqlcommand: Ein Tabellen- oder Abfragename (ohne umgebende Anführungszeichen oder eckige Klammern) oder eine Anweisung "SELECTSQL", in der Tabellen- und Feldnamen von eckigen Klammern oder Anführungszeichen umgeben sein können, um die Lesbarkeit zu verbessern.

directsql: Bei True wird der SQL-Befehl ohne Voranalyse an die Datenbank-Engine gesendet. Standard ist False. Bei Tabellen wird das Argument ignoriert. Bei Abfragen ist die angewandte Option diejenige, die festgelegt wurde, als die Abfrage definiert wurde.

Beispiel:

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

Fügt eine neue leere Tabelle vor einer bestehenden Tabelle oder am Ende der Tabellenliste ein.

Syntax:

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

Parameter:

sheetname: Der Name der neuen Tabelle.

beforesheet: Der Name (Zeichenfolge) oder Index (numerisch, beginnend mit 1) der Tabelle, vor der die neue Tabelle eingefügt werden soll. Dieses Argument ist optional und das Standardverhalten besteht darin, die Tabelle an der letzten Position einzufügen.

Beispiel:

Das folgende Beispiel fügt eine neue leere Tabelle mit dem Namen "SheetX" ein und platziert sie vor "SheetY":

In Basic

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

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

MoveRange

Verschiebt einen angegebenen Quellbereich in einen Zielbereich von Zellen. Die Methode gibt eine Zeichenfolge zurück, die den geänderten Zellbereich darstellt. Die Größe des modifizierten Bereichs wird vollständig durch die Größe des Quellbereichs bestimmt.

Syntax:

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

Parameter:

source: Der Quellbereich der Zellen als Zeichenfolge.

destination: Die Zielzelle als Zeichenfolge. Wenn ein Bereich angegeben ist, wird seine obere linke Zelle als Ziel betrachtet.

Beispiel:

In Basic

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

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

MoveSheet

Verschiebt eine vorhandene Tabelle und platziert sie vor einer angegebenen Tabelle oder am Ende der Tabellenliste.

Syntax:

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

Parameter:

sheetname: Der Name der zu verschiebenden Tabelle. Die Tabelle muss vorhanden sein oder es wird eine Ausnahme ausgelöst.

beforesheet: Der Name (Zeichenfolge) oder Index (numerisch, beginnend bei 1) der Tabelle, vor der die Originaltabelle platziert wird. Dieses Argument ist optional und das Standardverhalten besteht darin, die Tabelle an die letzte Position zu verschieben.

Beispiel:

Das folgende Beispiel verschiebt die vorhandene Tabelle „SheetS“ und platziert sie vor „SheetY“:

In Basic

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

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

Offset

Gibt einen neuen Bereich (als Zeichenfolge) zurück, der um eine bestimmte Anzahl von Zeilen und Spalten aus einem bestimmten Bereich versetzt ist.

Diese Methode hat das gleiche Verhalten wie die Funktion VERSCHIEBUNG des gleichnamigen Calc.

Syntax:

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

Parameter:

reference: Der Bereich als Zeichenfolge, den die Methode als Referenz verwendet, um die Operation "offset" auszuführen.

rows: Die Anzahl der Zeilen, um die der anfängliche Bereich nach oben (negativer Wert) oder nach unten (positiver Wert) verschoben wird. Verwenden Sie 0 (Standard), um in derselben Zeile zu bleiben.

columns: Die Anzahl der Spalten, um die der anfängliche Bereich nach links (negativer Wert) oder nach rechts (positiver Wert) verschoben wird. Verwenden Sie 0 (Standard), um in derselben Spalte zu bleiben.

height: Die vertikale Höhe für einen Bereich, der an der neuen Bereichsposition beginnt. Lassen Sie dieses Argument weg, wenn keine vertikale Größenanpassung erforderlich ist.

width: Die horizontale Breite für einen Bereich, der an der neuen Bereichsposition beginnt. Lassen Sie dieses Argument weg, wenn keine horizontale Größenanpassung erforderlich ist.

Die Argumente rows und columns dürfen nicht zu Null oder einer negativen Anfangszeile oder -spalte führen.

Die Argumente height und width dürfen nicht zu Null oder einer negativen Anzahl von Zeilen oder Spalten führen.

Beispiel:

In Basic

    oDoc.Offset("A1", 2, 2)
    ' SheetX.$C$3 (A1 um zwei Zeilen und zwei Spalten nach unten verschoben)
    oDoc.Offset("A1", 2, 2, 5, 6)
    ' SheetX.$C$3:$H$7 (A1 versetzt um zwei Zeilen und Spalten mit einer Breite von 5 Zeilen und 6 Spalten)
  
In Python

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

RemoveSheet

Entfernt eine vorhandene Tabelle aus dem Dokument.

Syntax:

svc.RemoveSheet(Tabellenname: str): bool

Parameter:

Tabellenname: Der Name der zu entfernenden Tabelle.

Beispiel:

In Basic

    oDoc.RemoveSheet("SheetY")
  
In Python

    myDoc.RemoveSheet("SheetY")
  

RenameSheet

Benennt die angegebene Tabelle um und gibt bei Erfolg True zurück.

Syntax:

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

Parameter:

sheetname: Der Name der umzubenennenden Tabelle.

newname: Der neue Name der Tabelle. Sie darf noch nicht existieren.

Beispiel:

In diesem Beispiel wird die aktive Tabelle in "SheetY" umbenannt:

In Basic

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

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

SetArray

Speichert den angegebenen Wert ab einer angegebenen Zielzelle. Der aktualisierte Bereich erweitert sich von der Zielzelle oder von der oberen linken Ecke des angegebenen Bereichs, um die Größe des Eingabearguments value aufzunehmen. Vektoren werden immer vertikal erweitert.

Die Methode gibt eine Zeichenfolge zurück, die den geänderten Bereich als Zellbereich darstellt.

Syntax:

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

Parameter:

targetcell: Die Zelle oder ein Bereich als Zeichenfolge, ab welcher/welchem der angegebene Wert gespeichert werden soll.

value: Ein Skalar, ein Vektor oder eine Matrix (in Python, ein- oder zweidimensionale Listen und Tupel) mit den neuen Werten, die aus der Zielzelle oder aus der oberen linken Ecke des Bereichs gespeichert werden sollen, wenn targetcell ein Bereich ist. Die neuen Werte müssen Zeichenfolgen, numerische Werte oder Datumsangaben sein. Bei anderen Typen werden die entsprechenden Zellen geleert.

Beispiel:

In Basic

Das folgende Beispiel verwendet die integrierte Funktion "DimArray", um eine Matrix zu erstellen und es dann in Zelle "A1" zu speichern:


    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)
  

Dieses Beispiel verwendet die Methode RangeInit des Matrixdienstes "ScriptForge" zum Erstellen einer Matrix mit Werten, die dann ab Zelle "A1" und abwärts gespeichert werden.


    ' Erste Spalte mit Werten von 1 bis 1000 füllen
    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

Um den gesamten Inhalt einer MAtrix in einer Tabelle auszugeben, verwenden Sie SetArray. Um den Inhalt eines Arrays nur innerhalb der Grenzen des Zielbereichs von Zellen auszugeben, verwenden Sie SetValue.


SetValue

Speichert den angegebenen Wert im angegebenen Bereich. Die Größe des modifizierten Bereichs entspricht der Größe des Zielbereichs.

Die Methode gibt eine Zeichenfolge zurück, die den geänderten Bereich als Zellbereich darstellt.

Syntax:

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

Parameter:

targetrange: Der Bereich, in dem der angegebene Wert als Zeichenfolge gespeichert werden soll.

value: Ein Skalar, ein Vektor oder eine Matrix mit den neuen Werten für jede Zelle des Bereichs. Die neuen Werte müssen Zeichenfolgen, numerische Werte oder Datumsangaben sein. Bei anderen Typen werden die entsprechenden Zellen geleert.

Der gesamte Bereich wird aktualisiert und der Rest der Tabelle bleibt unverändert. Wenn die Größe von value kleiner als die Größe von targetrange ist, dann werden die restlichen Zellen geleert.

Wenn die Größe von value größer als die Größe von targetrange ist, dann wird value nur teilweise kopiert, bis es die Größe von targetrange ausfüllt.

Vektoren werden vertikal expandiert, außer wenn targetrange eine Höhe von genau 1 Zeile hat.

Beispiel:

In Basic

    oDoc.SetValue("A1", 2)
    ' Die Matrix "Below the Value" ist kleiner als "TargetRange" (verbleibende Zellen werden geleert)
    oDoc.SetValue("A1:F1", Array(1, 2, 3))
    ' "Below the Value" und "TargetRange" haben die gleiche Größe
    oDoc.SetValue("A1:D2", SF_Array.AppendRow(Array(1, 2, 3, 4), Array(5, 6, 7, 8)))
  

Wenn Sie eine einzelne Zeile mit Werten füllen möchten, können Sie die Funktion Offset verwenden. Beachten Sie im folgenden Beispiel, dass arrData eine eindimensionale Matrix ist:


    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

Wendet die angegebene Zellvorlage auf den angegebenen Zielbereich an. Der gesamte Bereich wird aktualisiert und der Rest der Tabelle bleibt unberührt. Wenn die Zellvorlage nicht vorhanden ist, wird ein Fehler ausgelöst.

Die Methode gibt eine Zeichenfolge zurück, die den geänderten Bereich als Zellbereich darstellt.

Syntax:

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

Parameter:

targetrange: Der Bereich, auf den die Vorlage angewendet wird, als Zeichenfolge.

style: Der Name der anzuwendenden Zellvorlage.

Beispiel:

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

Fügt die angegebene(n) Formel(n) in den angegebenen Bereich ein. Die Größe des modifizierten Bereichs ist gleich der Größe des Bereichs.

Die Methode gibt eine Zeichenfolge zurück, die den geänderten Bereich als Zellbereich darstellt.

Syntax:

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

Parameter:

targetrange: Der Bereich zum Einfügen der Formeln als Zeichenfolge.

formula: Eine Zeichenfolge, ein Vektor oder eine Matrix von Zeichenfolgen mit den neuen Formeln für jede Zelle im Zielbereich.

Der gesamte Bereich wird aktualisiert und der Rest der Tabelle bleibt unverändert.

Wenn die angegebene Formel eine Zeichenfolge ist, wird die eindeutige Formel entlang des gesamten Bereichs mit Anpassung der relativen Referenzen eingefügt.

Wenn die Größe von formula kleiner als die Größe von targetrange ist, dann werden die restlichen Zellen geleert.

Wenn die Größe von formula größer ist als die Größe von targetrange, dann werden die Formeln nur teilweise kopiert, bis sie die Größe von targetrange ausfüllen.

Vektoren werden immer vertikal expandiert, außer wenn targetrange eine Höhe von genau einer Zeile hat.

Beispiel:

In Basic

    oDoc.SetFormula("A1", "=A2")
    ' Horizontaler Vektor, teilweise leer
    oDoc.SetFormula("A1:F1", Array("=A2", "=B2", "=C2+10"))
    ' D2 enthält die Formel "=H2"
    oDoc.SetFormula("A1:D2", "=E1")
  
In Python

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

SortRange

Sortiert den angegebenen Bereich nach bis zu 3 Spalten/Zeilen. Die Sortierreihenfolge kann je nach Spalte/Zeile variieren. Gibt eine Zeichenfolge zurück, die den geänderten Zellbereich darstellt. Die Größe des modifizierten Bereichs wird vollständig durch die Größe des Quellbereichs bestimmt.

Syntax:

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

Parameter:

range: Der zu sortierende Bereich als Zeichenfolge.

sortkeys: Ein Skalar (wenn 1 Spalte/Zeile) oder eine Matrix von Spalten-/Zeilennummern beginnend bei 1. Die maximale Anzahl von Schlüsseln ist 3.

sortorder: Ein Skalar oder eine Matrix von Zeichenfolgen, welche die Werte "ASC" (aufsteigend), "DESC" (absteigend) oder "" (standardmäßig aufsteigend) enthalten. Jedes Element wird mit dem entsprechenden Element in sortkeys gepaart. Wenn die Matrix sortorder kürzer als sortkeys ist, werden die restlichen Schlüssel in aufsteigender Reihenfolge sortiert.

destinationcell: Die Zielzelle des sortierten Zellenbereichs als Zeichenfolge. Wenn ein Bereich angegeben ist, wird nur die obere linke Zelle berücksichtigt. Standardmäßig wird der Quellbereich überschrieben.

containsheader: Bei True wird die erste Zeile/Spalte nicht sortiert.

casesensitive: Nur für Zeichenfolgenvergleiche. Standard = Falsch

sortcolumns: Bei True werden die Spalten von links nach rechts sortiert. Standard = False: Zeilen werden von oben nach unten sortiert.

Beispiel:

In Basic

    ' Bereich nach Spalten A (aufsteigend) und C (absteigend) sortieren
    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 Basic-Routinen oder -Identifikatoren von ScriptForge mit einem Unterstrich "_" sind für internen Gebrauch reserviert. Sie sind nicht für den Einsatz in Basic-Macros gedacht.