Služba SFDocuments.Calc

KnihovnaSFDocuments poskytuje řadu metod a vlastností usnadňujících správu a obsluhu dokumentů LibreOffice Calc.

Některé metody, zděděné ze služby Document, jsou obecné pro všechny typy dokumentů, zatímco jiné jsou specifické pro modul SF_Calc.

Modul SF_Calc se zaměřuje na:

Volání služby

Služba Calc úzce souvisí se službou UI knihovny ScriptForge. Níže je uvedeno několik příkladů, jak lze vytvořit instanci služby Calc.

V Basicu

V následující části kódu se vytvoří instance služby Calc, která odpovídá aktuálně aktivnímu dokumentu Calcu.


    Set oDoc = CreateScriptService("Calc")
  

Jiným způsobem, jak vytvořit instanci služby Calc, je použít službu UI. V následujícím příkladu se vytvoří nový dokument Calcu, proměnná oDoc je instancí služby Calc:


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

Nebo pomocí metody OpenDocument ze služby UI:


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

Instanci služby Calc je také možné vytvořit pomocí metody CreateScriptService:


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

V příkladu výše je "MyFile.ods" název otevřeného dokumentu. Není-li tento argument uveden, použije se aktivní okno.

Po použití se doporučuje uvolnit zdroje:


    Set oDoc = oDoc.Dispose()
  

Jestliže však byl dokument zavřen metodou CloseDocument, není výše uvedený příkaz pro uvolnění zdrojů nutný.

V Pythonu

    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

Použití předpony "SFDocuments." není při volání této služby povinné.


Definice

Mnoho metod vyžaduje argument "Sheet" nebo "Range". Jednotlivé buňky jsou považovány za speciální případ oblasti (Range).

Oba mohou být vyjádřeny buď jako řetězec, nebo jako odkaz (tj. objekt), a to podle situace:

Příklad:

V následujícím příkladu jsou data z dokumentu A (otevřeného pouze pro čtení a skrytého) zkopírována do dokumentu B.

V Basicu

    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)
  
V Pythonu

    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

Název listu jako řetězec (string) nebo objekt (object) získaný z vlastnosti .Sheet.

Zkratka "~" (vlnovka) představuje aktuální list.

RangeName

Řetězec označující sadu sousedních buněk umístěných na listu aktuální instance nebo objekt (object) získaný z vlastnosti .Range.

Zkratka "~" (vlnovka) představuje aktuální výběr nebo první vybranou oblast, pokud je vybráno více oblastí.

Zkratka "*" představuje všechny použité buňky.

Název listu je u oblasti nepovinný (výchozí = aktivní list). Uzavírající jednoduché uvozovky a znaky $ jsou povoleny, ale ignorují se.

tip

Kromě vlastnosti CurrentSelection je ve službě Calc uvažována pouze jediná oblast buněk.


Příklady platných oblastí

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

Jediná buňka

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

Jediná oblast s více buňkami

'$SheetX'.*

Všechny použité buňky na daném listu

1) '$SheetX'.A:A (sloupec A)
2) 3:5 (řádky 3 až 5)

Všechny buňky v sousedních sloupcích či řádcích až po poslední použitou buňku

myRange

Oblast pojmenovaná "myRange" na úrovni sešitu

1) ~.someRange
2) SheetX.someRange

Název oblasti na úrovni listu

myDoc.Range("SheetX.D2:F6")

Oblast na listu SheetX v souboru přiřazeném k instanci Calcu myDoc

~.~ nebo ~

Aktuální výběr na aktivním listu


Vlastnosti

Pro dokumenty Calcu lze rovněž použít všechny vlastnosti obecné pro jakýkoliv dokument. Další informace naleznete na stránce služby Document.

Vlastnosti specifické pro dokumenty Calcu jsou:

Název

Pouze pro čtení

Argument

Typ

Popis

CurrentSelection

ne

Žádný

String nebo pole řetězců

Jediná vybraná oblast jako řetězec nebo seznam vybraných oblastí jako pole.

Height

ano

RangeName jako String

Long

Počet řádků (>= 1) v zadané oblasti.

LastCell

ano

SheetName jako String

String

Poslední použitá buňka na zadaném listu ve formátu "A1"

LastColumn

ano

SheetName jako String

Long

Poslední použitý sloupec na zadaném listu

LastRow

ano

SheetName jako String

Long

Poslední použitý řádek na zadaném listu

Range

ano

RangeName jako String

Object

Odkaz na oblast, který lze použít jako argument metod jako CopyToRange

Sheet

ano

SheetName jako String

Object

Odkaz na list, který lze použít jako argument metod jako CopySheet

Sheets

ano

Žádný

pole řetězců (String)

Seznam názvů všech existujících listů

Width

ano

RangeName jako String

Long

Počet sloupců (>= 1) v zadané oblasti

XCellRange

ano

RangeName jako String

Object

Objekt UNO com.sun.star.Table.XCellRange

XSpreadsheet

ano

SheetName jako String

Object

Objekt UNO com.sun.star.sheet.XSpreadsheet


tip

Další informace o objektech UNO XCellRange a XSpreadsheet se dozvíte v dokumentaci LibreOffice API.


Metody

Seznam metod služby 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

Je-li zadán argument SheetName, zadaný list se aktivuje a stane se aktuálně vybraným. Pokud tento argument chybí, aktivuje se okno s dokumentem.

Syntaxe:

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

Parametry:

sheetname: Název listu, který se má v dokumentu aktivovat. Výchozí hodnotou je prázdný řetězec, který znamená, že se místo změny aktivního listu aktivuje okno s dokumentem.

Příklad:

V následujícím příkladu se v aktuálně aktivním dokumentu aktivuje list s názvem "Sheet4".

V Basicu

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

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

Aktivování listu má význam pouze v dokumentech Calcu. Chcete-li se ujistit, že pracujete s dokumentem Calcu, použijte vlastnost isCalc pro objekt s dokumentem. Tato vlastnost vrátí True, jedná-li se o dokument Calcu, v opačném případě vrátí False.


ClearAll

Vymaže v zadané oblasti veškerý obsah a formáty.

Syntaxe:

svc.ClearAll(range: str)

Parametry:

range: Oblast, která se má vymazat, jako řetězec.

Příklad:

V Basicu

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

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

ClearFormats

Vymaže v zadané oblasti formáty a styly.

Syntaxe:

svc.ClearFormats(range: str)

Parametry:

range: Oblast, jejíž formáty a styly se mají vymazat, jako řetězec.

Příklad:

V Basicu

      oDoc.ClearFormats("SheetX.*")
  
V Pythonu

    myDoc.ClearFormats("SheetX.*")
  

ClearValues

Vymaže v zadané oblasti hodnoty a vzorce.

Syntaxe:

svc.ClearValues(range: str)

Parametry:

range: Oblast, jejíž hodnoty a vzorce se mají vymazat, jako řetězec.

Příklad:

V Basicu

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

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

CopySheet

Zkopíruje určený list před existující list nebo na konec seznamu listů. List, který se má zkopírovat, se může nacházet v jakémkoliv otevřeném dokumentu Calcu. Je-li kopírování úspěšné, vrátí True.

Syntaxe:

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

Parametry:

sheetname: Název listu, který se má zkopírovat, jako řetězec nebo odkaz na list jako objekt.

newname: Název listu, který se má vložit. Je nutné, aby se název v dokumentu ještě nepoužíval.

beforesheet: Název (řetězec) nebo index (číslo začínající od 1) listu, před nějž se má zkopírovaný list vložit. Tento argument je nepovinný, ve výchozím chování se zkopírovaný list přidá na poslední pozici.

Příklad:

V Basicu

V následujícím příkladu se vytvoří kopie listu "SheetX" a umístí se do aktuálního dokumentu jako poslední list. Název zkopírovaného listu je "SheetY".


    Dim oDoc as Object
    ' Získá z aktivního okna objekt Document
    Set oDoc = CreateScriptService("Calc")
    oDoc.CopySheet("SheetX", "SheetY")
  

V příkladu níže se zkopíruje list "SheetX" ze souboru "FileA.ods" a vloží se na poslední pozici souboru "FileB.ods" pod názvem "SheetY".


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

    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

Chcete-li kopírovat listy mezi otevřenými dokumenty, použijte metodu CopySheet. Při kopírování listů ze zavřených dokumentů použijte CopySheetFromFile.


CopySheetFromFile

Zkopíruje určený list ze zavřeného dokumentu a vloží jej před existující list nebo na konec seznamu listů do souboru, na který odkazuje objekt Document.

Pokud neexistuje soubor, nastane chyba. Není-li soubor platným souborem Calcu, vloží se prázdný list. Pokud zdrojový list ve vstupním souboru neexistuje, na nově vložený list se nahoru umístí chybová zpráva.

Syntaxe:

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

Parametry:

filename: Určuje soubor, který se má otevřít. Musí odpovídat zápisu SF_FileSystem.FileNaming. Je nutné, aby soubor nebyl chráněn heslem.

sheetname: Název listu, který se má zkopírovat, jako řetězec.

newname: Název zkopírovaného listu, který se má do dokumentu vložit. Je nutné, aby se název v dokumentu ještě nepoužíval.

beforesheet: Název (řetězec) nebo index (číslo začínající od 1) listu, před nějž se má zkopírovaný list vložit. Tento argument je nepovinný, ve výchozím chování se zkopírovaný list přidá na poslední pozici.

Příklad:

V následujícím příkladu se zkopíruje list "SheetX" ze souboru "myFile.ods" a vloží se na první pozici od názvem "SheetY" do dokumentu, na nějž odkazuje objekt "oDoc".

V Basicu

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

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

CopyToCell

Zkopíruje určenou zdrojovou oblast (hodnoty, vzorce a formáty) do cílové oblasti či buňky. Metoda se chová stejně jako operace Kopírovat/Vložit z oblasti do jediné buňky.

Vrátí řetězec představující upravenou oblast buněk. Velikost upravené oblasti je plně určena velikostí zdrojové oblasti.

Zdrojová oblast se může nacházet v jiném otevřeném dokumentu.

Syntaxe:

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

Parametry:

sourcerange: Zdrojová oblast jako řetězec, pokud se nachází v témže dokumentu, nebo jako odkaz, pokud se nachází v jiném otevřeném dokumentu Calcu.

destinationcell: Cílová buňka, do níž se zkopírovaná oblast buněk vloží, jako řetězec. Je-li zadána oblast, použije se pouze její levá horní buňka.

Příklad:

V Basicu

Následuje příklad se zdrojovou a cílovou oblastí v témže souboru:


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

Příklad níže ukazuje, jak zkopírovat oblast z jiného otevřeného dokumentu Calcu:


    Dim ui as Variant : ui = CreateScriptService("UI")
    Dim oDocSource As Object, oDocDestination As Object
    ' Otevře zdrojový dokument na pozadí (jako skrytý)
    Set oDocSource = ui.OpenDocument("C:\SourceFile.ods", Hidden := True, ReadOnly := True)
    Set oDocDestination = CreateScriptService("Calc")
    oDocDestination.CopyToCell(oDocSource.Range("Sheet1.C2:C4"), "SheetT.A5")
    ' Nezapomeňte zdrojový dokument zavřít, protože byl otevřen jako skrytý
    oDocSource.CloseDocument()
  
V Pythonu

    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

Metoda CopyToCell napodobuje operaci Kopírovat/Vložit z oblasti do jediné buňky. Chcete-li napodobit operaci Kopírovat/Vložit z oblasti do větší oblasti (s několikrát zopakovanými buňkami), použijte metodu CopyToRange.


CopyToRange

Zkopíruje určenou zdrojovou oblast (hodnoty, vzorce a formáty) do cílové oblasti, a to směrem dolů či doprava. Metoda napodobuje chování operace Kopírovat/Vložit ze zdrojové oblasti do větší cílové oblasti.

Metoda vrátí řetězec představující upravenou oblast buněk.

Zdrojová oblast se může nacházet v jiném otevřeném dokumentu.

Syntaxe:

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

Parametry:

sourcerange: Zdrojová oblast jako řetězec, pokud se nachází v témže dokumentu, nebo jako odkaz, pokud se nachází v jiném otevřeném dokumentu Calcu.

destinationrange: Cílová oblast pro zkopírované buňky jako řetězec.

Příklad:

V Basicu

Kopírování v rámci jednoho dokumentu:


    oDoc.CopyToRange("SheetX.A1:F10", "SheetY.C5:J5")
    ' Vrátí řetězec pro oblast: "$SheetY.$C$5:$J$14"
  

Kopírování z jednoho souboru do jiného:


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

    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

Použije na funkci Average, Count, Max, Min nebo Sum, a to na všechny buňky zadané oblasti, které obsahují číselné hodnoty.

Syntaxe:

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

Parametry:

range: Oblast, na niž se má funkce použít, jako řetězec.

Příklad:

V následujícím příkladu se použije funkce Sum na oblast "A1:A1000" z aktuálně vybraného listu:

V Basicu

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

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

Buňky v zadané oblasti, které obsahují text, jsou všemi těmito funkcemi ignorovány. Například metoda DCount spočítá pouze buňky s čísly, nikoliv buňky s textem.


Forms

V závislosti na předaných parametrech tato metoda vrátí:

Syntaxe:

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

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

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

Parametry:

sheetname: Název listu, z něhož se formulář získá, jako řetězec.

form: Název nebo index odpovídající formuláři uloženému na zadaném listu. Pokud tento argument chybí, metoda vrátí seznam s názvy všech formulářů z daného listu.

Příklad:

V následujících příkladech se na prvním řádku získají názvy všech formulářů uložených na listu "Sheet1", na druhém řádku se vrátí objekt Form z formuláře pojmenovaného "Form_A" a uloženého na listu "Sheet1".

V Basicu

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

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

GetColumnName

Převede číslo sloupce z rozsahu 1 až 1024 na odpovídající písmeno (sloupec "A", "B", ..., "AMJ"). Nachází-li se zadané číslo sloupce mimo povolený rozsah, vrátí se řetězec nulové délky.

Syntaxe:

svc.GetColumnName(columnnumber: int): str

Parametry:

columnnumber: Číslo sloupce jako celočíselná hodnota z intervalu 1 až 1024.

Příklad:

V Basicu

Zobrazí dialog s názvem třetího sloupce, který je ve výchozím nastavení "C".


    MsgBox oDoc.GetColumnName(3)
  
V Pythonu

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

Maximální počet sloupců na listu Calcu je 1024.


GetFormula

Získá vzorec či vzorce uložené v zadané oblasti buněk, a to jako jeden řetězec, nebo jako jednorozměrné či dvourozměrné pole řetězců.

Syntaxe:

svc.GetFormula(range: str): any

Parametry:

range: Oblast, z níž se mají vzorce získat, jako řetězec.

Příklad:

V Basicu

V následujícím příkladu se vrátí pole 3 × 2 se vzorcemi z oblasti "A1:B3" (3 řádky krát 2 sloupce):


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

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

GetValue

Získá hodnotu či hodnoty uložené v zadané oblasti buněk, a to jako jednu hodnotu, nebo jako jednorozměrní či dvourozměrné pole. Každá hodnota je buď číslo typu double, nebo řetězec.

Syntaxe:

svc.GetValue(range: str): any

Parametry:

range: Oblast, z níž se mají hodnoty získat, jako řetězec.

Příklad:

V Basicu

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

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

Jestliže buňka obsahuje datum, vrátí se číslo tomuto datu odpovídající. Ve skriptech Basicu lze číselné hodnoty převést na data vestavěnou funkcí CDate. Ve skriptech Pythonu použijte funkci CDate ze služby Basic.


ImportFromCSVFile

Naimportuje obsah textového souboru formátu CSV a umístí jej do zadané cílové buňky.

Před vložením obsahu souboru CSV se z cílové oblasti vymaže veškerý obsah a formáty. Velikost takto upravené oblasti je plně určena obsahem vstupního souboru.

Metoda vrátí řetězec představující upravenou oblast buněk.

Syntaxe:

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

Parametry:

filename: Označuje soubor, který se má otevřít. Musí odpovídat zápisu SF_FileSystem.FileNaming.

destinationcell: Cílová buňka pro vložení naimportovaných dat, a to jako řetězec. Je-li místo buňky zadána oblast, použije se pouze její levá horní buňka.

filteroptions: Argumenty vstupního filtru pro CSV. Výchozí filtr předpokládá následující nastavení:

Příklad:

V Basicu

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

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

Podrobnosti o možnostech CSV filtru naleznete na wiki stránce Filter Options.


ImportFromDatabase

Naimportuje obsah tabulky databáze, dotazu nebo sady výsledků, tj. výsledku SQL příkazu SELECT, a vloží jej do cílové buňky.

Před vložením naimportovaného obsahu se z cílové oblasti vymaže veškerý obsah a formáty. Velikost takto upravené oblasti je plně určena obsahem z tabulky nebo dotazu.

Metoda vrátí v případě úspěšného importu True.

Syntaxe:

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

Parametry:

filename: Označuje soubor, který se má otevřít. Musí odpovídat zápisu SF_FileSystem.FileNaming.

registrationname: Název, podle něhož lze databázi nalézt v registru databází. Tento argument je ignorován, je-li zadán argument filename.

destinationcell: Cílová buňka pro naimportovaná data, a to jako řetězec. Je-li místo buňky zadána oblast, použije se pouze její levá horní buňka.

sqlcommand: Název tabulky či dotazu (bez uzavírajících uvozovek nebo hranatých závorek) nebo SQL příkaz SELECT, ve kterém je možné v zájmu čitelnosti uzavřít názvy tabulek a polí do hranatých závorek či uvozovek.

directsql: Je-li True, SQL příkaz se odešle databázovému enginu bez předchozí analýzy. Výchozí je False. U tabulek se tento argument ignoruje. U dotazů se použije taková možnost, jaká byly nastavena při definování dotazu.

Příklad:

V Basicu

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

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

InsertSheet

Vloží nový prázdný list před některý existující nebo na konec seznamu listů.

Syntaxe:

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

Parametry:

sheetname: Název nového listu.

beforesheet: Název (řetězec) nebo index (číslo začínající od 1) listu, před nějž se má nový list vložit. Tento argument je nepovinný, ve výchozím chování se list přidá na poslední pozici.

Příklad:

V následujícím příkladu se vloží nový prázdný list pojmenovaný "SheetX" a umístí se před list "SheetY":

V Basicu

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

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

MoveRange

Přesune určenou oblast do cílové oblasti buněk. Metoda vrátí řetězec představující upravenou oblast buněk. Velikost takto upravené oblasti je plně určena velikostí zdrojové oblasti.

Syntaxe:

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

Parametry:

source: Zdrojová oblast buněk, a to jako řetězec.

destination: Cílová buňka jako řetězec. Je-li zadána oblast, jako cílová se použije její levá horní buňka.

Příklad:

V Basicu

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

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

MoveSheet

Přesune již existující list a umístí jej před určený list nebo na konec seznamu listů.

Syntaxe:

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

Parametry:

sheetname: Název listu, který se má přesunout. List musí existovat, jinak nastane výjimka.

beforesheet: Název (řetězec) nebo index (číslo začínající od 1) listu, před nějž se má původní list umístit. Tento argument je nepovinný, ve výchozím chování se list přesune na poslední pozici.

Příklad:

V následujícím příkladu se přesune existující list "SheetX" a umístí se před list "SheetY".

V Basicu

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

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

Offset

Vrátí novou oblast (jako řetězec) posunutou od zadané oblasti o určitý počet řádků a sloupců.

Metoda se chová stejně jako stejnojmenná funkce Calcu Offset.

Syntaxe:

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

Parametry:

reference: Oblast jako řetězec, kterou metoda použije pro provedení posunu jako referenční.

rows: Počet řádků, o který se má původní oblast posunout nahoru (záporná hodnota) nebo dolů (kladná hodnota). Výchozí 0 znamená zůstat na stejném řádku.

columns: Počet sloupců, o který se má původní oblast posunout doleva (záporná hodnota) nebo doprava (kladná hodnota). Výchozí 0 znamená zůstat ve stejném sloupci.

height: Svislá výška oblasti začínající na pozici nové oblasti. Pokud tento argument vynecháte, nebude nutné měnit ve svislém rozměru velikost.

width: Vodorovná výška oblasti začínající na pozici nové oblasti. Pokud tento argument vynecháte, nebude nutné měnit ve vodorovném rozměru velikost.

Argumenty rows a columns nesmí vést k nulovému nebo zápornému počátečnímu řádku nebo sloupci.

Argumenty height a width nesmí vést k nulovému nebo zápornému počtu řádků a sloupců.

Příklad:

V Basicu

    oDoc.Offset("A1", 2, 2)
    'SheetX.$C$3 (A1 posunuto o dva řádky dolů a dva sloupce doprava)
    oDoc.Offset("A1", 2, 2, 5, 6)
    'SheetX.$C$3:$H$7 (A1 posunuto o dva řádky a sloupce s rozměry 5 řádků a 6 sloupců)
  
V Pythonu

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

RemoveSheet

Odstraní z dokumentu existující list.

Syntaxe:

svc.RemoveSheet(sheetname: str): bool

Parametry:

sheetname: Název listu, který se má odstranit.

Příklad:

V Basicu

    oDoc.RemoveSheet("SheetY")
  
V Pythonu

    myDoc.RemoveSheet("SheetY")
  

RenameSheet

Přejmenuje zadaný list a v případě úspěchu vrátí True.

Syntaxe:

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

Parametry:

sheetname: Název listu, který se má přejmenovat.

newname: Nový název listu, nesmí ještě existovat.

Příklad:

V tomto příkladu je aktivní list přejmenován na "SheetY":

V Basicu

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

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

SetArray

Uloží zadanou hodnotu do oblasti začínající určenou cílovou buňkou. Cílová oblast se rozšíří z cílové buňky nebo z levého horního rohu zadané oblasti tak, aby odpovídala velikosti argumentu value. Vektory oblast rozšíří vždy ve svislém směru.

Metoda vrátí řetězec představující upravenou oblast buněk.

Syntaxe:

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

Parametry:

targetcell: Buňka nebo oblast (jako řetězec), od níž se začne ukládat zadaná hodnota.

value: Skalár, vektor nebo pole (v Pythonu jednorozměrné či dvourozměrné seznamy a n-tice) s novými hodnotami, které se mají uložit do cílové buňky nebo od levého horního rohu oblasti, pokud je targetcell oblast. Nové hodnoty musí být řetězce, číselné hodnoty nebo data. Při použití jiných typů budou odpovídající buňky prázdné.

Příklad:

V Basicu

V následujícím příkladu se vestavěnou funkcí DimArray vytvoří pole a to se poté uloží do buňky "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)
  

V tomto příkladu se pomocí metody RangeInit ze služby ScriptForge Array vytvoří pole s hodnotami, které se poté uloží do buňky "A1" a dalších buněk směrem dolů.


    ' Vyplní první sloupec hodnotami od 1 do 1000
    oDoc.SetArray("Sheet1.A1", SF_Array.RangeInit(1, 1000))
  
V Pythonu

    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

Metodu SetArray použijte, chcete-li na list uložit úplný obsah pole. Chcete-li uložit obsah pole omezený hranicemi cílové oblasti buněk, použijte metodu SetValue.


SetValue

Uloží zadanou hodnotu do určené oblasti. Velikost upravené oblasti je rovna velikosti cílové oblasti.

Metoda vrátí řetězec představující upravenou oblast buněk.

Syntaxe:

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

Parametry:

targetrange: Oblast, kam se má uložit zadaná hodnota, jako řetězec.

value: Skalár, vektor nebo pole s novými hodnotami pro buňky oblasti. Nové hodnoty musí být řetězce, číselné hodnoty nebo data. Při použití jiných typů budou odpovídající buňky prázdné.

Aktualizuje se celá oblast a zbytek listu zůstane beze změny. Je-li velikost hodnoty value menší než velikost oblasti targetrange, budou přebývající buňky prázdné.

Pokud je velikost hodnoty value větší než velikost oblasti targetrange, zkopíruje se value pouze částečně, dokud nevyplní velikost targetrange.

Vektory oblast rozšíří ve svislém směru s výjimkou případu, kdy má oblast targetrange výšku 1 řádek.

Příklad:

V Basicu

    oDoc.SetValue("A1", 2)
    ' Pole Value je menší než oblast TargetRange (přebývající buňky jsou prázdné)
    oDoc.SetValue("A1:F1", Array(1, 2, 3))
    ' Value a TargetRange mají stejnou velikost
    oDoc.SetValue("A1:D2", SF_Array.AppendRow(Array(1, 2, 3, 4), Array(5, 6, 7, 8)))
  

Chcete-li vyplnit jeden řádek hodnotami, můžete použít funkci Offset. V následujícím příkladu se předpokládá, že je proměnná arrData jednorozměrným polem:


    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)
  
V Pythonu

    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

Použije určený styl buňky na zadanou cílovou oblast. Aktualizuje se celá oblast a zbytek listu se ponechá beze změny. Pokud styl buňky neexistuje, nastane chyba.

Metoda vrátí řetězec představující upravenou oblast buněk.

Syntaxe:

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

Parametry:

targetrange: Oblast, na niž se má styl použít, jako řetězec.

style: Název stylu, který se má použít.

Příklad:

V Basicu

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

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

SetFormula

Vloží zadaný vzorec (či pole vzorců) do určené cílové oblasti. Velikost upravené oblasti je rovna velikosti cílové oblasti.

Metoda vrátí řetězec představující upravenou oblast buněk.

Syntaxe:

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

Parametry:

targetrange: Oblast, do níž se mají vzorce vložit, jako řetězec.

formula: Řetězec nebo vektor či pole řetězců s novými vzorci pro buňky cílové oblasti.

Aktualizuje se celá oblast a zbytek listu zůstane beze změny.

Pokud je zadaným vzorcem jediný řetězec, vloží se do každé buňky oblasti jedinečný vzorec s přizpůsobenými relativními odkazy.

Pokud je velikost argumentu formula menší než velikost oblasti targetrange, budou přebývající buňky prázdné.

Pokud je velikost argumentu formula větší než velikost oblasti targetrange, zkopírují se vzorce pouze částečně, dokud nevyplní velikost targetrange.

Vektory oblast vždy rozšíří ve svislém směru s výjimkou případu, kdy má oblast targetrange výšku 1 řádek.

Příklad:

V Basicu

    oDoc.SetFormula("A1", "=A2")
    ' Vodorovný vektor, částečně prázdný
    oDoc.SetFormula("A1:F1", Array("=A2", "=B2", "=C2+10"))
    ' D2 obsahuje vzorec "=H2"
    oDoc.SetFormula("A1:D2", "=E1")
  
V Pythonu

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

SortRange

Seřadí zadanou oblast podle až 3 sloupců/řádků. Pořadí řazení se může pro jednotlivé sloupce/řádky lišit. Vrátí řetězec představující upravenou oblast buněk. Velikost upravené oblasti je plně určena velikostí zdrojové oblasti.

Syntaxe:

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

Parametry:

range: Oblast, která se má seřadit, jako řetězec.

sortkeys: Skalár (v případě 1 sloupce/řádků) nebo pole čísel sloupců/řádků začínajících od 1. Maximální počet klíčů je 3.

sortorder: Skalár nebo pole řetězců obsahující hodnoty "ASC" (vzestupně), "DESC" (sestupně) nebo "" (znamená výchozí vzestupně). Každá položka je přiřazena odpovídající položce argumentu sortkeys. Je-li pole sortorder kratší než sortkeys, přebývající klíče jsou seřazeny ve vzestupném pořadí.

destinationcell: Cílová buňka seřazené oblasti buněk, a to jako řetězec. Je-li zadána oblast, použije se pouze její levá horní buňka. Ve výchozím nastavení je přepsána zdrojová oblast.

containsheader: Je-li True, první řádek/sloupec se neseřadí.

casesensitive: Pouze pro porovnání řetězců (výchozí = False).

sortcolumns: Je-li True, sloupce se seřadí zleva doprava. Výchozí = False: řádky se seřadí shora dolů.

Příklad:

V Basicu

    ' Seřadí oblast podle sloupců A (vzestupně) a C (sestupně)
    oDoc.SortRange("A2:J200", Array(1, 3), Array("ASC", "DESC"), CaseSensitive := True)
  
V Pythonu

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

Všechny procedury nebo identifikátory knihovny ScriptForge, které jsou uvozeny podtržítkem "_", jsou určeny pro interní použití. Není zamýšleno je používat v makrech Basicu.