Služba SFDocuments.Calc

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

Služba SFDocuments.Calc je podtřídou služby SFDocuments.Document. Ke všem metodám a vlastnostem služby Document lze přistupovat také pomocí instance služby Calc.

Služba Calc se zaměřuje na:

• Manipulaci s listy v dokumentu Calcu (kopírování, vkládání, přesun apod.)

• Výměnu dat mezi datovými strukturami Basicu a oblastmi Calcu

• Kopírování a importování velkého množství dat

Na této stránce nápovědy jsou popsány pouze metody a vlastnosti specifické pro dokumenty Calcu.

Volání služby

Před používáním služby Calc je nutné načíst či naimportovat knihovnu ScriptForge pomocí:

• V makrech Basicu je nutné načíst knihovnu ScriptForge následujícím příkazem:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Ve skriptech Pythonu je nezbytné import z modulu scriptforge:
from scriptforge import CreateScriptService

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 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í zadání názvu okna pro metodu 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.

Službu Calc lze také zavolat pomocí dokumentu, na který odkazuje objekt ThisComponent. To je užitečné zejména při spouštění makra z prostředí Basic IDE.

    Dim oDoc As Object
    Set oDoc = CreateScriptService("Calc", ThisComponent)
  

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ý.

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

    bas = CreateScriptService("Basic")
    myDoc = CreateScriptService("Calc", bas.ThisComponent)
  

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:

• V rámci určité instance služby Calc se listy a oblasti zadávají jako řetězce, například "Sheet1" nebo "D2:F6".

• Vlastnosti .Sheet a .Range vracejí odkaz, který může být použit jako argument metod volaných z jiné instance služby Calc.

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.

    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)
  

    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

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 při definování oblasti nepovinný. Není-li žádný zadán, použije se aktivní list. Uzavírající jednoduché uvozovky a znaky $ jsou povoleny, ale ignorují se.

Pokud je SheetName zadán jako řetězec, je použití jednoduchých uvozovek uzavírajících název listu vyžadováno v případě, že název obsahuje mezeru " " nebo tečku ".".

Následující příklady ilustrují, v jakých případech je použití jednoduchých uvozovek povinné:

      ' Použití jednoduchých uvozovek je nepovinné
      oDoc.clearAll("SheetA.A1:B10")
      oDoc.clearAll("'SheetA'.A1:B10")
      ' Použití jednoduchých uvozovek je vyžadováno
      oDoc.clearAll("'Sheet.A'.A1:B10")
    

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

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:

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

Metody

A1Style

Vrátí adresu oblasti jako řetězec, a to na základě souřadnic v listu, tj. čísel řádků a sloupců.

Je-li zadána pouze jedna dvojice souřadnic, vrátí se adresa jediné buňky. Dalšími argumenty je možné určit pravou dolní buňku obdélníkové oblasti.

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

row1, column1: Určují čísla řádku a sloupce pro levou horní buňky v uvažované oblasti. Čísla řádků a sloupců začínají od 1.

row2, column2: Určují čísla řádku a sloupce pro pravou dolní buňku uvažované oblasti. Nejsou-li tyto argumenty uvedeny nebo jsou-li menší než hodnoty row1 či column1, vrátí se adresa oblasti s jedinou buňkou představovanou souřadnicemi row1 a column1.

sheetname: Název listu, který se má připojit k vracené adrese oblasti. Tento list musí existovat. Výchozí hodnotou je "~", odpovídající aktuálně aktivnímu listu.

V následujících příkladech v Basicu a Pythonu se předpokládá, že aktuálně aktivním listem je "Sheet1".

    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
  

    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
  

Metodu A1Style lze kombinovat s mnoha vlastnostmi a metodami služby Calc, které vyžadují jako argument oblast, například GetValue, GetFormula, ClearAll apod.

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.

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

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.

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

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

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

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.

Charts

Vrátí seznam názvů všech objektů s grafy na zadaném listu nebo jedinou instanci služby Chart.

• Je-li určen pouze argument sheetname, vrátí se pole řetězců začínající od 0, které obsahuje názvy všech grafů.

• Je-li určen argument chartname, vrátí se jediný objekt odpovídající požadovanému grafu. Tento graf musí existovat.

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

sheetname: Název listu, pro který se má zjistit seznam grafů nebo kde se nachází zadaný graf.

chartname: Uživatelem definovaný název objektu s grafem, který se má vrátit. Pokud graf uživatelem definovaný název nemá, je možné použít interní název objektu. Pokud tento argument chybí, vrátí se seznam názvů grafů na zadaném listu.

Názvy přiřazené ke grafům zjistíte na postranní liště Navigátor v kategorii Objekty OLE.

V následujícím příkladu se zobrazí počet objektů s grafy na listu "Sheet1".

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

V následujícím příkladu se přistupuje ke grafu s názvem "MyChart" na listu "Sheet1" a vypíše se jeho typ.

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

    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

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

Lze zadat vzorec, pomocí kterého se vyfiltrují buňky, které mají být ovlivněny.

svc.ClearAll(range: str, opt filterformula: str, opt filterscope: str)

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

filterformula: Vzorec Calcu, který se použije na zadanou oblast pro určení toho, které buňky budou ovlivněny. Tento vzorec musí vracet True nebo False. Není-li tento argument zadán, budou ovlivněny všechny buňky v oblasti.

filterscope: Určuje, jak se vzorec filterformula přizpůsobí zadané oblasti. Tento argument je povinný, pokud je zadán argument filterformula. Možné jsou následující hodnoty:

• "CELL": Vzorec zadaný v argumentu filterformula se přizpůsobí každé buňce v oblasti range.

• "ROW": Vzorec zadaný v argumentu filterformula se přizpůsobí každému řádku v oblasti range.

• "COLUMN": Vzorec zadaný v argumentu filterformula se přizpůsobí každému sloupci v oblasti range.

    ' Vymaže všechny buňky v oblasti ListX.A1:J10
    oDoc.ClearAll("ListX.A1:J10")
    ' Vymaže všechny buňky v oblasti ListX.A1:J10, jejichž hodnota je větší než 100
    oDoc.ClearAll("SheetX.A1:J10", "=ListX.A1>100", "CELL")
    ' Vymaže všechny řádky v oblasti ListX.A1:J10, jejichž součet je větší než 500
    oDoc.ClearAll("ListX.A1:J10", "=SUM(ListX.A1:J1)>100", "ROW")
    ' Vymaže všechny sloupce v oblasti ListX.A1:J10, jejichž součet je větší než 500
    oDoc.ClearAll("ListX.A1:J10", "=SUM(ListX.A1:A10)>100", "COLUMN")
  

    myDoc.ClearAll("ListX.A1:F10")
    myDoc.ClearAll("ListX.A1:J10", "=ListX.A1>100", "CELL")
    myDoc.ClearAll("ListX.A1:J10", "=SUM(ListX.A1:J1)>100", "ROW")
    myDoc.ClearAll("ListX.A1:J10", "=SUM(ListX.A1:A10)>100", "COLUMN")
  

ClearFormats

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

Lze zadat vzorec, pomocí kterého se vyfiltrují buňky, které mají být ovlivněny.

svc.ClearFormats(range: str, opt filterformula: str, opt filterscope: str)

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

      oDoc.ClearFormats("SheetX.*")
  

    myDoc.ClearFormats("SheetX.*")
  

Příklady použití argumentů filterformula a filterscope naleznete v dokumentaci metody ClearAll.

ClearValues

Vymaže v zadané oblasti hodnoty a vzorce.

Lze zadat vzorec, pomocí kterého se vyfiltrují buňky, které mají být ovlivněny.

svc.ClearValues(range: str, opt filterformula: str, opt filterscope: str)

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

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

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

Příklady použití argumentů filterformula a filterscope naleznete v dokumentaci metody ClearAll.

CompactLeft

Smaže v zadané oblasti sloupce, které odpovídají filtru vyjádřenému v podobě vzorce Calcu. Filtr bude použit na každý sloupec, aby se zjistilo, zda má být smazán, či nikoli.

Mazání sloupce může být omezeno na výšku určené oblasti, nebo se může týkat výšky celého listu, tj. smažou se celé sloupce.

Tato metoda vrátí řetězec s adresou zmenšené oblasti. Jsou-li smazány všechny sloupce, vrátí se prázdný řetězec.

Pokud je vybrána oblast buněk, volání této metody výběr neovlivní.

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

range: Oblast, z níž budou sloupce smazány, a to jako řetězec.

wholecolumn: Pokud je tato možnost nastavena na True, z listu se budou mazat celé sloupce. Výchozí hodnotou je False, což znamená, že se mazání sloupců omezí na výšku oblasti zadané jako range.

filterformula: Filtr, který se má použít na každý sloupec, aby určil, zda se má sloupec smazat. Filtr je vyjádřen jako vzorec Calcu, který se má použít na první sloupec. Pokud tento vzorec vrátí pro nějaký sloupec True, takový sloupec se smaže. Výchozí filtr odstraní všechny prázdné sloupce.

Předpokládejme například, že je vybrána oblast A1:J200 (výška = 200), a výchozí vzorec je tedy =(COUNTBLANK(A1:A200)=200). To znamená, že pokud je všech 200 buněk prvního sloupce (sloupec A) prázdných, tento sloupec se smaže. Mějte na paměti, že vzorec je vyjádřen pouze vzhledem k prvnímu sloupci. Vnitřně metoda CompactLeft tento vzorec pro všechny zbývající sloupce zobecní.

Funkce Calcu použité v argumentu filterformula je nutné zapsat pomocí anglických názvů. Úplný seznam anglických názvů funkcí Calcu naleznete na wiki stránce List of Calc Functions.

    ' Smaže všechny prázdné sloupce v oblasti G1:L10 na listu List1
    newrange = oDoc.CompactLeft("List1.G1:L10")
    ' Následující příklad je podobný, z listu se však smažou celé sloupce
    newrange = oDoc.CompactLeft("List1.G1:L10", WholeColumn := True)
    ' Smaže všechny sloupce, v nichž je první řádek označen písmenem "X"
    newrange = oDoc.CompactLeft("List1.G1:L10", FilterFormula := "=(G1=""X"")")
    ' Smaže všechny sloupce, v nichž je součet hodnot lichý
    newrange = oDoc.CompactLeft("List1.G1:L10", FilterFormula := "=(MOD(SUM(G1:G10);2)=1)")
  

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

CompactUp

Smaže v zadané oblasti řádky, které odpovídají filtru vyjádřenému v podobě vzorce Calcu. Filtr bude použit na každý řádek, aby se zjistilo, zda má být smazán, či nikoli.

Mazání řádku může být omezeno na šířku určené oblasti, nebo se může týkat šířky celého listu, tj. smažou se celé řádky.

Tato metoda vrátí řetězec s adresou zmenšené oblasti. Jsou-li smazány všechny řádky, vrátí se prázdný řetězec.

Pokud je vybrána oblast buněk, volání této metody výběr neovlivní.

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

range: Oblast, z níž budou řádky smazány, a to jako řetězec.

wholerow: Pokud je tato možnost nastavena na True, z listu se budou mazat celé řádky. Výchozí hodnotou je False, což znamená, že se mazání řádků omezí na šířku oblasti zadané jako range.

filterformula: Filtr, který se má použít na každý řádek, aby určil, zda se má řádek smazat. Filtr je vyjádřen jako vzorec Calcu, který se má použít na první řádek. Pokud tento vzorec vrátí pro nějaký řádek True, takový řádek se smaže. Výchozí filtr odstraní všechny prázdné řádky.

Předpokládejme například, že je vybrána oblast A1:J200 (šířka = 10), a výchozí vzorec je tedy =(COUNTBLANK(A1:J1)=10). To znamená, že pokud je všech 10 buněk prvního řádku (řádek 1) prázdných, tento řádek se smaže. Mějte na paměti, že vzorec je vyjádřen pouze vzhledem k prvnímu řádku. Vnitřně metoda CompactUp tento vzorec pro všechny zbývající řádky zobecní.

Funkce Calcu použité ve vzorci v argumentu filterformula je nutné zapsat pomocí anglických názvů. Úplný seznam anglických názvů funkcí Calcu naleznete na wiki stránce List of Calc Functions.

    ' Smaže všechny prázdné řádky v oblasti G1:L10 na listu List1
    newrange = oDoc.CompactUp("List1.G1:L10")
    ' Následující příklad je podobný, z listu se však smažou celé řádky
    newrange = oDoc.CompactUp("List1.G1:L10", WholeRow := True)
    ' Smaže všechny řádky, na nichž je první sloupec označen písmenem "X"
    newrange = oDoc.CompactUp("List1.G1:L10", FilterFormula := "=(G1=""X"")")
    ' Smaže všechny řádky, na nichž je součet hodnot lichý
    newrange = oDoc.CompactUp("List1.G1:L10", FilterFormula := "=(MOD(SUM(G1:L1);2)=1)")
  

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

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.

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

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.

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

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

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.

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

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.

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

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

    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.

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

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.

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

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

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.

• Jestliže je výška (resp. šířka) cílové oblasti větší než 1 řádek (resp. sloupec), musí být výška (resp. šířka) zdrojové oblasti menší nebo rovna výšce (resp. šířce) cílové oblasti. V opačném případě se nic neprovede.

• Je-li výška (resp. šířka) cílové oblasti 1, cílová oblast se rozšíří směrem dolů (resp. doprava) až do výšky (resp. šířky) zdrojové 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.

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

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.

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

    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

Vytvoří nový objekt s grafem, který zobrazuje data z určené oblasti. S vráceným objektem s grafem lze dále nakládat pomocí služby Chart.

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

chartname: Uživatelem definovaný název grafu, který se má vytvořit. Název musí být v rámci listu jedinečný.

sheetname: Název listu, na který se graf umístí.

range: Oblast, která se použije jako zdroj dat grafu. Může odkazovat na libovolný list dokumentu Calcu.

columnheader: Je-li True, řádek oblasti umístěný nejvíc nahoře se použije jako popisky osy kategorií nebo legendy (výchozí = False).

rowheader: Je-li True, sloupec oblasti umístěný nejvíc vlevo se použije jako popisky osy kategorií nebo legendy (výchozí = False).

V následujícím příkladu v Basicu a Pythonu je vytvořen z dat obsažených v oblasti "A1:B5" na listu "Sheet1" graf, který je umístěn na list "Sheet2".

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

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

Jak dále pracovat s objekty s grafem, naleznete na stránce o službě Chart knihovny ScriptForge. U grafu je možné měnit vlastnosti jako typ, popisy os či umístění.

CreatePivotTable

Vytvoří novou kontingenční tabulku s vlastnostmi zadanými argumenty předávanými této metodě.

Pro kontingenční tabulku je nutné zadat název. Jestliže na cílovém listu již kontingenční tabulka s tímto názvem existuje, bude bez upozornění nahrazena.

Metoda vrátí řetězec obsahující oblast, do níž byla nová kontingenční tabulka umístěna.

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

pivottablename: Uživatelem stanovený název nové kontingenční tabulky.

sourcerange: Oblast obsahující zdrojová data, a to jako řetězec. Předpokládá se, že první řádek obsahuje názvy polí, které kontingenční tabulka používá.

targetcell: Levá horní buňky oblasti, do níž bude kontingenční tabulka umístěna. Je-li zadána oblast, použije se pouze její levá horní buňka.

datafields: Jediný řetězec nebo pole obsahující řetězce, které určují názvy polí a funkce, které se mají použít. Je-li zadáno pole, musí odpovídat syntaxi Array("NázevPole[;Funkce]", ...).

Povolenými funkcemi jsou: Sum, Count, Average, Max, Min, Product, CountNums, StDev, StDevP, Var, VarP a Median. Názvy funkcí je nutné zadat v angličtině. Pokud jsou všechny hodnoty číselné, je výchozí funkcí Sum, v opačném případě je výchozí funkcí Count.

rowfields: Jediný řetězec nebo pole s názvy polí, které se použijí jako řádky kontingenční tabulky.

columnfields: Jediný řetězec nebo pole s názvy polí, které se použijí jako sloupce kontingenční tabulky.

filterbutton: Určuje, zda bude nad kontingenční tabulkou zobrazeno tlačítko filtru (výchozí = True).

rowtotals: Určuje, zda bude ke kontingenční tabulce přidán sloupec se součty řádků (výchozí = True).

columntotals: Určuje, zda bude ke kontingenční tabulce přidán řádek se součty sloupců (výchozí = True).

    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("Položka", "Stát", "Tým", "2002", "2003", "2004"), _
        Array("Knihy", "Česká republika", "Jana", 14788, 30222, 23490), _
        Array("Sušenky", "Česká republika", "Jana", 26388, 15641, 32849), _
        Array("Pera", "Česká republika", "Jana", 16569, 32675, 25396), _
        Array("Knihy", "Česká republika", "Václav", 21961, 21242, 29009), _
        Array("Sušenky", "Česká republika", "Václav", 26142, 22407, 32841))
    sTable = oDoc.SetArray("A1", vData)
    sPivot = oDoc.CreatePivotTable("PT1", sTable, "H1", _
        Array("2002", "2003;count", "2004;average"), _ ' Tři datová pole
        "Položka", _ ' Jediné pole pro řádky
        Array("Stát", "Tým"), False) ' Dvě pole pro sloupce
  

    ui = CreateScriptService("UI")
    doc = ui.CreateDocument("Calc")
    vData = [["Položka", "Stát", "Tým", "2002", "2003", "2004"],
             ["Knihy", "Česká republika", "Jana", 14788, 30222, 23490],
             ["Sušenky", "Česká republika", "Jana", 26388, 15641, 32849],
             ["Pera", "Česká republika", "Jana", 16569, 32675, 25396)],
             ["Knihy", "Česká republika", "Václav", 21961, 21242, 29009],
             ["Sušenky", "Česká republika", "Václav", 26142, 22407, 32841]]
    sTable = doc.SetArray("A1", vData)
    sPivot = doc.CreatePivotTable("PT1", sTable, "H1",
                                  ["2002", "2003;count", "2004;average"],
                                  "Položka",
                                  ["Stát", "Tým"], False)
  

Další informace o kontingenčních tabulkách v aplikaci LibreOffice Calc naleznete na stránce nápovědy Kontingenční tabulka.

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, avšak s výjimkou hodnot mimo použitý filtr a hodnot ze skrytých řádků a sloupců. Toto chování je stejné jako u funkcí ze stavového řádku.

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

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

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

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

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

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.

ExportRangeToFile

Exportuje zadanou oblast jako obrázek nebo soubor PDF.

V případě úspěšného uložení cílového souboru vrátí metoda True.

Skryté řádky či sloupce se ze zadané oblasti do cílového souboru neexportují.

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

range: Název listu nebo oblast buněk, která se má exportovat, jako řetězec.

filename: Název souboru, který se má uložit. Musí odpovídat zápisu SF_FileSystem.FileNaming.

imagetype: Určuje typ cílového souboru. Možnými hodnotami jsou "jpeg", "pdf" (výchozí) a "png".

overwrite: Je-li True, cílový soubor může být přepsán (výchozí = False).

    ' Exportuje celý sešit jako soubor PDF
    oDoc.ExportRangeToFile("SheetX", "C:\Temp\image.pdf")
    ' Exportuje oblast jako soubor PNG a přepíše cílový soubor, pokud existuje
    oDoc.ExportRangeToFile("SheetX.A1:D10", "C:\Temp\image.png", "png", Overwrite := True)
  

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

Forms

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

• Pole začínající od 0 (případně n-tice v Pythonu) s názvy všech formulářů obsažených na zadaném listu (pokud chybí argument form)

• Instanci služby SFDocuments.Form představující formulář uvedený jako argument.

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

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

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

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.

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

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

    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.

svc.GetColumnName(columnnumber: int): str

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

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

    MsgBox oDoc.GetColumnName(3)
  

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

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ů.

Názvy funkcí Calcu použité ve vracených vzorcích jsou v angličtině. Úplný seznam anglických názvů funkcí Calcu naleznete na wiki stránce List of Calc Functions.

svc.GetFormula(range: str): any

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

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

    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.

svc.GetValue(range: str): any

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

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

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

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.

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

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í:

• Kódování vstupního souboru je UTF8.

• Oddělovačem polí je čárka, středník nebo znak tabulátoru.

• Oddělovačem řetězců je dvojitá uvozovka (").

• Použijí se všechny řádky.

• Řetězce v uvozovkách se naformátují jako text.

• Rozpoznávají se speciální čísla.

• Všechny sloupce se považují za text, pokud nejsou rozpoznány jako platná čísla.

• Výchozím jazykem je angličtina (USA), což znamená, že oddělovačem desetinných míst je tečka (".") a oddělovačem tisíců čárka (",").

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

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

Podrobnosti o možnostech CSV filtru naleznete na stránce Možnosti CSV filtru.

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.

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

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.

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

    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ů.

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

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.

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

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

    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.

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

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.

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

    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ů.

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

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.

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

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

    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.

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

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ů.

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

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

OpenRangeSelector

Otevře nemodální dialogové okno pro výběr oblasti v dokumentu a vrátí řetězec obsahující vybranou oblasti.

Tato metoda otevře stejné dialogové okno, které se v LibreOffice používá při stisknutí tlačítka "Zmenšit". Toto tlačítko má například dialogové okno Nástroje - Hledat řešení napravo od pole Buňka se vzorcem.

Metoda nemění aktuální výběr.

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

title: Název dialogového okna jako řetězec.

selection: Nepovinná oblast, která je vybrána při zobrazení okna.

singlecell: Je-li True (výchozí), je povolen pouze výběr jediné buňky. Je-li False, je možné vybrat oblast.

closeafterselect: Je-li True (výchozí), dialogové okno se po provedení výběru ihned zavře. Je-li False, uživatel může výběr podle potřeby opakovaně měnit a poté okno ručně zavřít.

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

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

Printf

Vrátí vstupní řetězec se znaky tokenů nahrazenými hodnotami ze zadané oblasti.

Metoda nemění aktuální výběr.

Pomocí této metody je možné rychle získat určité části názvu oblasti, například název listu nebo první buňku sloupce či řádku, a použít je při vytváření adresy nové oblasti.

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

inputstr: Řetězec obsahující tokeny, které budou nahrazeny odpovídajícími hodnotami z oblasti range.

range: Název RangeName, ze kterého se hodnoty získají. Obsahuje-li název listu, je nutné, aby tento list existoval.

tokencharacter: Znak označující tokeny. Jako výchozí znak je nastaveno procento ("%"). Je možné použít následující tokeny:

• %S - Název listu obsahující oblast, je-li to potřeba, včetně jednoduchých uvozovek.

• %R1 - Číslo řádku pro levou horní buňku oblasti.

• %C1 - Písmeno sloupce pro levou horní buňku oblasti.

• %R2 - Číslo řádku pro pravou dolní buňku oblasti.

• %C2 - Písmeno sloupce pro pravou dolní buňku oblasti.

V následujícím příkladu je zjištěna hodnota každého prvku názvu RangeName definovaném pro oblast sRange a tyto hodnoty jsou použity k sestavení zprávy.

    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)
  

Metodu Printf lze zkombinovat s metodou SetFormula a vytvořit tak vzorce ve více buňkách. Například můžete chtít vytvořit vzorce, pomocí nichž sečtete hodnoty v každém řádky tabulky s číselnými hodnotami v oblasti "A1:E10", a výsledky umístit do oblasti "F1:F10":

    Dim sFormula as String, sRange as String
    sRange = "A1:E10"
    ' Povšimněte si použití znaku "$"
    sFormula = "=SUM($%C1%R1:$%C2%R1)"
    oDoc.SetFormula("F1:F10", oDoc.Printf(sFormula, sRange))
  

    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

Tato metoda odešle obsah zadaného listu na výchozí tiskárnu nebo na tiskárnu definovanou metodou SetPrinter služby Document.

Vrátí True, pokud byl list úspěšně vytištěn.

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

sheetname: Název listu, který se má vytisknout, výchozí je aktivní list.

pages: Stránky, které se mají vytisknout, jako řetězec podobný tomu, který se zadává v uživatelském rozhraní, například: "1-4;10;15-18". Výchozí jsou všechny stránky.

copies: Počet kopií. Výchozí je 1.

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

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

RemoveDuplicates

Odstraní ze zadané oblasti duplicitní řádky. Při určování toho, zda jsou řádky duplicitní, se uvažují pouze určité sloupce oblasti.

Metoda vrátí řetězec obsahující výslednou oblast.

Odstraňování duplicitních řádků začíná na prvním řádku oblasti a pokračuje směrem dolů. To znamená, že pokud jsou dva či více řádků duplicitních, zachová se pouze první z nich.

svc.RemoveDuplicates(range: str, opt columns: int[0..*], header: bool = False, casesensitive: bool = False, mode: str = "COMPACT"): str

range: Oblast, z níž se duplicitní řádky odstraní, jako řetězec.

columns: Pole obsahující čísla sloupců, které se mají při určování toho, zda jsou řádky duplicitní, uvažovat. Je-li tento argument ponechán prázdný, použije se pouze první sloupec. Položky tohoto pole se musí nacházet v intervalu od 1 do šířky oblasti.

header: Určuje, zda je první řádek záhlavím (výchozí = False).

casesensitive: Určuje, zda se má při porovnávání řetězců rozlišovat velikost písmen (výchozí = False).

mode: Určuje, co se má s duplicitními řádky stát. Při hodnotě mode = "CLEAR" se obsah duplicitních řádků ze sešitu jednoduše odstraní a buňky zůstanou prázdné. Při mode = "COMPACT" se odstraní obsah včetně celých řádků (výchozí = "COMPACT").

    ' Odstraní řádky, které mají duplicitní hodnoty ve sloupci A
    ' Všechny nepovinné argumenty jsou nastaveny na výchozí hodnoty
    oDoc.RemoveDuplicates("A1:B10")
    ' Odstraní duplicitní řádky s předpokladem, že první řádek obsahuje záhlaví
    ' Pro určení, zda je řádek duplicitní, se použijí sloupce A a B
    ' Buňky obsahující duplicitní hodnoty zůstanou prázdné
    oDoc.RemoveDuplicates("A1:D10", columns := Array(1, 2), header := True, mode := "CLEAR")
  

    myDoc.RemoveDuplicates("A1:B10")
    myDoc.RemoveDuplicates("A1:D10", columns = (1, 2), header = True, mode = "CLEAR")
  

RemoveSheet

Odstraní z dokumentu existující list.

svc.RemoveSheet(sheetname: str): bool

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

    oDoc.RemoveSheet("SheetY")
  

    myDoc.RemoveSheet("SheetY")
  

RenameSheet

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

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

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

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

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

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

    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.

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

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é.

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

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

    myDoc.SetArray("Sheet1.A1", tuple(i + 1 for i in range(1000)))
  

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.

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.

svc.SetCellStyle(targetrange: str, style: str, opt filterformula: str, opt filterscope: str): str

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

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

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

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

Příklady použití argumentů filterformula a filterscope naleznete v dokumentaci metody ClearAll.

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.

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

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.

Funkce Calcu použité v argumentu formula je nutné zapsat pomocí anglických názvů. Úplný seznam anglických názvů funkcí Calcu naleznete na wiki stránce List of Calc Functions.

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

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

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.

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

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.

    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)
  

    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)
  

ShiftDown

Přesune zadanou oblast buněk dolů tím, že před ni vloží prázdné řádky. Aktuální výběr se nezmění.

Podle hodnoty argumentu wholerow mohou vložené řádky zabírat buď šířku určené oblasti, nebo všech sloupců v řádku.

Metoda vrátí řetězec odpovídající novému umístění počáteční oblasti.

Jestliže by posunutá oblast překročila hranice listu, přesun se neprovede.

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

range: Oblast, nad niž se vloží řádky, jako řetězec.

wholerow: Je-li False (výchozí), šířka vložených řádků bude stejná jako šířka určené oblasti range. V opačném případě budou vložené řádky zabírat všechny sloupce listu.

rows: Počet řádků, které se mají vložit. Výchozí hodnotou je výška původní oblasti range. Počet řádků musí být kladné číslo.

    ' Přesune oblast "A3:D3" o jeden řádek dolů; ovlivněny budou pouze sloupce A až D
    oDoc.ShiftDown("A3:D3")
    ' Vložené řádky zabírají všechny sloupce na listu
    oDoc.ShiftDown("A3:D3", WholeRow := True)
    ' Přesune oblast "A3:D3" o pět řádků dolů
    oDoc.ShiftDown("A3:D3", Rows := 5)
    ' Přesune oblast "A3:D10" o dva řádky dolů a zobrazí nové umístění původní oblasti
    Dim sNewRange as String
    sNewRange = oDoc.ShiftDown("A3:D10", Rows := 2)
    MsgBox sNewRange   ' $Sheet1.$A$5:$D$12
  

    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

Smaže sloupce zadané oblasti umístěné nejvíce vlevo a přesune doleva všechny buňky napravo od ovlivněné oblasti. Aktuální výběr se nezmění.

Podle hodnoty argumentu wholecolumn mohou smazané sloupce zabírat buď výšku určené oblasti, nebo všech řádků ve sloupci.

Metoda vrátí řetězec představující umístění zbývající části počáteční oblasti. Pokud se z původní oblasti smažou všechny buňky, vrátí se prázdný řetězec.

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

range: Oblast, z níž se buňky smažou, jako řetězec.

wholecolumn: Je-li False (výchozí), výška smazaných sloupců bude stejná jako výška určené oblasti range. V opačném případě budou smazané sloupce zabírat všechny řádky listu.

columns: Počet sloupců, které se mají z určené oblasti range smazat. Výchozí hodnotou je šířka této oblasti, která je zároveň maximální hodnotou tohoto argumentu.

    ' Smaže oblast "B3:B6" a přesune doleva všechny buňky napravo od ní
    oDoc.ShiftLeft("B3:B6")
    ' Smaže první sloupec oblasti "A3:D6"
    oDoc.ShiftLeft("A3:D6", Columns := 1)
    ' Smazané sloupce (A až D) zabírají všechny řádky listu
    oDoc.ShiftLeft("A3:D6", WholeColumn := True)
  

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

ShiftUp

Smaže řádky zadané oblasti umístěné nejvíce nahoře a přesune nahoru všechny buňky dolů od ovlivněné oblasti. Aktuální výběr se nezmění.

Podle hodnoty argumentu wholerow mohou smazané řádky zabírat buď šířku určené oblasti, nebo všech sloupců v řádku.

Metoda vrátí řetězec představující umístění zbývající části počáteční oblasti. Pokud se z původní oblasti smažou všechny buňky, vrátí se prázdný řetězec.

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

range: Oblast, z níž se buňky smažou, jako řetězec.

wholerow: Je-li False (výchozí), šířka smazaných řádků bude stejná jako šířka určené oblasti range. V opačném případě budou smazané řádky zabírat všechny sloupce listu.

columns: Počet řádků, které se mají z určené oblasti range smazat. Výchozí hodnotou je výška této oblasti, která je zároveň maximální hodnotou tohoto argumentu.

    ' Smaže oblast "A3:D3" a přesune nahoru všechny buňky dolů od ní
    oDoc.ShiftUp("A3:D3")
    ' Smaže první řádek oblasti "A3:D6"
    oDoc.ShiftUp("A3:D6", Rows := 1)
    ' Smazané řádky zabírají všechny sloupce na listu
    oDoc.ShiftUp("A3:D6", WholeRow := True)
  

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

ShiftRight

Přesune zadanou oblast buněk doprava tím, že před ni vloží prázdné sloupce. Aktuální výběr se nezmění.

Podle hodnoty argumentu wholecolumn mohou vložené sloupce zabírat buď výšku určené oblasti, nebo všech řádků ve sloupci.

Metoda vrátí řetězec odpovídající novému umístění počáteční oblasti.

Jestliže by posunutá oblast překročila hranice listu, přesun se neprovede.

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

range: Oblast, nalevo od níž se vloží prázdné sloupce, jako řetězec.

wholecolumn: Je-li False (výchozí), výška vložených sloupců bude stejná jako výška určené oblasti range. V opačném případě budou vložené sloupce zabírat všechny řádky listu.

columns: Počet sloupců, které se mají vložit. Výchozí hodnotou je šířka původní oblasti range.

    ' Přesune oblast "A3:A6" o jeden sloupec doprava; ovlivněny budou pouze řádky 3 až 6
    oDoc.ShiftRight("A3:A6")
    ' Přesune oblast "A3:A6" o pět sloupců doprava
    oDoc.ShiftRight("A3:A6", Columns := 5)
    ' Vložené sloupce zabírají všechny řádky na listu
    oDoc.ShiftRight("A3:A6", WholeColumn := True)
  

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

SortRange

Seřadí zadanou oblast podle libovolného počtu sloupců/řádků. Pořadí řazení se může pro jednotlivé sloupce/řádky lišit. Pokud je počet řadicích klíčů > 3, oblast se seřadí několikrát, a to postupně podle skupin 3 klíčů počínaje posledním z nich. Vrátí řetězec představující upravenou oblast buněk. Velikost upravené oblasti je plně určena velikostí zdrojové oblasti. Velikost upravené oblasti je plně určena velikostí zdrojové oblasti.

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

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.

sortorder: Skalár nebo pole řetězců obsahující hodnoty "ASC" (vzestupně) nebo "DESC" (sestupně). 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ů.

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

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

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 nebo skriptech Pythonu.