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:

note

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

note

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

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

    myDoc = ui.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 = 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")
    
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

Návratový typ

Popis

CurrentSelection

ne

Žádný

String nebo pole řetězců

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

FirstCell

ano

SheetName nebo RangeName jako String

String

Vrátí první použitou buňku v zadané oblasti nebo listu.

FirstColumn

ano

SheetName nebo RangeName jako String

Long

Vrátí číslo sloupce nejvíc vlevo v zadané oblasti nebo listu.

FirstRow

ano

SheetName nebo RangeName jako String

Long

Vrátí číslo řádku nejvíc nahoře v zadané oblasti nebo listu.

Height

ano

RangeName jako String

Long

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

LastCell

ano

SheetName nebo RangeName jako String

String

Vrátí poslední použitou buňku v zadané oblasti nebo listu.

LastColumn

ano

SheetName nebo RangeName jako String

Long

Poslední použitý sloupec v zadané oblasti nebo listu.

LastRow

ano

SheetName nebo RangeName jako String

Long

Poslední použitý řádek v zadané oblasti nebo listu.

Range

ano

RangeName jako String

Object

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

Region

ano

RangeName jako String

String

Vrátí adresu nejmenší oblasti, která obsahuje zadanou oblast, a to tak, aby byla hraničila s prázdnými buňkami nebo s okraji listu. Výsledek odpovídá použití zkratky na zadanou oblast.

Sheet

ano

SheetName jako String

Object

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

SheetName

ano

RangeName jako String

String

Vrátí název listu pro zadanou oblast adres.

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.

XSheetCellCursor

ano

RangeName jako String

Object

Objekt UNO com.sun.star.sheet.XSheetCellCursor. Po přesunu kurzoru je možné výslednou adresu oblasti získat jako vlastnost UNO AbsoluteName objektu s kurzorem. Tato vlastnost vrátí řetězec, který lze použít jako argument vlastností a metod služby Calc.

XSpreadsheet

ano

SheetName jako String

Object

Objekt UNO com.sun.star.sheet.XSpreadsheet.


tip

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


Metody

Seznam metod služby Calc

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

DCount
DMax
DMin
DSum
ExportRangeToFile
Forms
GetColumnName
GetFormula
GetValue
ImportFromCSVFile
ImportFromDatabase
InsertSheet
MoveRange
MoveSheet
Offset

OpenRangeSelector
PrintOut
Printf
RemoveSheet
RenameSheet
SetArray
SetValue
SetCellStyle
SetFormula
ShiftDown
ShiftLeft
ShiftRight
ShiftUp
SortRange


A1Style

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.

Syntaxe:

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

Parametry:

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.

Příklad:

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

V Basicu

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

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

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.

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

    ui = CreateScriptService("UI")
    myDoc = ui.GetDocument(ui.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.


Charts

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

Syntaxe:

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

Parametry:

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.

tip

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


Příklad:

V Basicu

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

    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.

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

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.

note

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


Syntaxe:

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

Parametry:

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

Příklad:

V Basicu

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

    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.

note

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


Syntaxe:

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

Parametry:

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

Příklad:

V Basicu

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

    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.

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

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

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

Syntaxe:

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

Parametry:

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

Příklad:

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

V Basicu

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

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

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.

Syntaxe:

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

Parametry:

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

Příklad:

V Basicu

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

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

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.

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.


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.

note

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


Syntaxe:

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

Parametry:

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

Příklad:

V Basicu

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

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

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

    bas = CreateScriptService("Basic")
    bas.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 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.

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)
  

OpenRangeSelector

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

note

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.

Syntaxe:

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

Parametry:

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.

Příklad:

V Basicu

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

    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.

tip

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.


Syntaxe:

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

Parametry:

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:

Příklad:

V Basicu

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

    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.

Syntaxe:

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

Parametry:

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é rozhraní, například: "1-4;10;15-18". Výchozí jsou všechny stránky.

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

Příklad:

V Basicu

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

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

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

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.

note

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


Syntaxe:

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

Parametry:

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

V Basicu

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

    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.

Syntaxe:

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

Parametry:

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.

Příklad:

V Basicu

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

    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.

Syntaxe:

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

Parametry:

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.

Příklad:

V Basicu

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

    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.

note

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


Syntaxe:

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

Parametry:

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

V Basicu

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

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

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


Podpořte nás!