Obsah
Rejstřík 🔎︎

# Služba SFDocuments.Calc

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

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

Modul SF_Calc se zaměřuje na:

- 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

## Volání služby

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

##### V Basicu

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

        Set oDoc = CreateScriptService("Calc")

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

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

Nebo pomocí metody OpenDocument ze služby UI:

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

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

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

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

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

        Set oDoc = oDoc.Dispose()

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

##### V Pythonu

        myDoc = CreateScriptService("Calc")

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

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

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

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.

### Příklad:

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

##### V Basicu

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

##### V Pythonu

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

### SheetName

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

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

### RangeName

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

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

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

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

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

Příklady platných oblastí
1) '$SheetX'.D2 2) $D$2 | Jediná buňka
1) '$SheetX'.D2:F6 2) D2:D10 | Jediná oblast s více buňkami
'$SheetX'.* | Všechny použité buňky na daném listu
1) '$SheetX'.A:A (sloupec A) 2) 3:5 (řádky 3 až 5) | Všechny buňky v sousedních sloupcích či řádcích až po poslední použitou buňku
myRange | Oblast pojmenovaná "myRange" na úrovni sešitu
1) ~.someRange 2) SheetX.someRange | Název oblasti na úrovni listu
myDoc.Range("SheetX.D2:F6") | Oblast na listu SheetX v souboru přiřazeném k instanci Calcu myDoc
~.~ nebo ~ | Aktuální výběr na aktivním listu

## Vlastnosti

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

Vlastnosti specifické pro dokumenty Calcu jsou:

Název | Pouze pro čtení | Argument | Typ | Popis
CurrentSelection | ne | Žádný | String nebo pole řetězců | Jediná vybraná oblast jako řetězec nebo seznam vybraných oblastí jako pole.
Height | ano | RangeName jako String | Long | Počet řádků (>= 1) v zadané oblasti.
LastCell | ano | SheetName jako String | String | Poslední použitá buňka na zadaném listu ve formátu "A1"
LastColumn | ano | SheetName jako String | Long | Poslední použitý sloupec na zadaném listu
LastRow | ano | SheetName jako String | Long | Poslední použitý řádek na zadaném listu
Range | ano | RangeName jako String | Object | Odkaz na oblast, který lze použít jako argument metod jako CopyToRange
Sheet | ano | SheetName jako String | Object | Odkaz na list, který lze použít jako argument metod jako CopySheet
Sheets | ano | Žádný | pole řetězců (String) | Seznam názvů všech existujících listů
Width | ano | RangeName jako String | Long | Počet sloupců (>= 1) v zadané oblasti
XCellRange | ano | RangeName jako String | Object | Objekt UNO com.sun.star.Table.XCellRange
XSpreadsheet | ano | SheetName jako String | Object | Objekt UNO com.sun.star.sheet.XSpreadsheet

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

## Metody

Seznam metod služby Calc
Activate ClearAll ClearFormats ClearValues CopySheet CopySheetFromFile CopyToCell CopyToRange DAvg DCount | DMax DMin DSum Forms GetColumnName GetFormula GetValue ImportFromCSVFile ImportFromDatabase InsertSheet | MoveRange MoveSheet Offset RemoveSheet RenameSheet SetArray SetValue SetCellStyle SetFormula SortRange

## Activate

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

### Syntaxe:

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

### Parametry:

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

### Příklad:

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

##### V Basicu

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

##### V Pythonu

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

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

## ClearAll

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

### Syntaxe:

svc.ClearAll(range: str)

### Parametry:

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

### Příklad:

##### V Basicu

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

##### V Pythonu

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

## ClearFormats

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

### Syntaxe:

svc.ClearFormats(range: str)

### Parametry:

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

### Příklad:

##### V Basicu

          oDoc.ClearFormats("SheetX.*")

##### V Pythonu

        myDoc.ClearFormats("SheetX.*")

## ClearValues

Vymaže v zadané oblasti hodnoty a vzorce.

### Syntaxe:

svc.ClearValues(range: str)

### Parametry:

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

### Příklad:

##### V Basicu

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

##### V Pythonu

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

## CopySheet

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

### Syntaxe:

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

### Parametry:

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

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

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

### Příklad:

##### V Basicu

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

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

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

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

##### V Pythonu

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

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

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

## CopySheetFromFile

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

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

### Syntaxe:

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

### Parametry:

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

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

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

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

### Příklad:

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

##### V Basicu

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

##### V Pythonu

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

## CopyToCell

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

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

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

### Syntaxe:

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

### Parametry:

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

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

### Příklad:

##### V Basicu

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

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

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

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

##### V Pythonu

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

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.

### Syntaxe:

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

### Parametry:

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

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

### Příklad:

##### V Basicu

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

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

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

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

##### V Pythonu

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

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

## DAvg, DCount, DMax, DMin and DSum

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

### Syntaxe:

svc.DAvg(range: str): float

svc.DCount(range: str): float

svc.DMax(range: str): float

svc.DMin(range: str): float

svc.DSum(range: str): float

### Parametry:

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

### Příklad:

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

##### V Basicu

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

##### V Pythonu

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

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

## Forms

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

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

### Syntaxe:

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

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

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

### Parametry:

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

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

### Příklad:

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

##### V Basicu

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

##### V Pythonu

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

## GetColumnName

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

### Syntaxe:

svc.GetColumnName(columnnumber: int): str

### Parametry:

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

### Příklad:

##### V Basicu

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

        MsgBox oDoc.GetColumnName(3)

##### V Pythonu

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

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

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

- 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 (",").

### Příklad:

##### V Basicu

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

##### V Pythonu

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

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

## ImportFromDatabase

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

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

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

### Syntaxe:

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

### Parametry:

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

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

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

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

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

### Příklad:

##### V Basicu

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

##### V Pythonu

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

## InsertSheet

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

### Syntaxe:

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

### Parametry:

sheetname: Název nového listu.

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

### Příklad:

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

##### V Basicu

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

##### V Pythonu

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

## MoveRange

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

### Syntaxe:

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

### Parametry:

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

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

### Příklad:

##### V Basicu

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

##### V Pythonu

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

## MoveSheet

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

### Syntaxe:

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

### Parametry:

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

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

### Příklad:

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

##### V Basicu

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

##### V Pythonu

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

## Offset

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

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

### Syntaxe:

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

### Parametry:

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

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

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

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

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

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

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

### Příklad:

##### V Basicu

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

##### V Pythonu

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

## RemoveSheet

Odstraní z dokumentu existující list.

### Syntaxe:

svc.RemoveSheet(sheetname: str): bool

### Parametry:

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

### Příklad:

##### V Basicu

        oDoc.RemoveSheet("SheetY")

##### V Pythonu

        myDoc.RemoveSheet("SheetY")

## RenameSheet

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

### Syntaxe:

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

### Parametry:

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

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

### Příklad:

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

##### V Basicu

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

##### V Pythonu

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

## SetArray

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

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

### Syntaxe:

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

### Parametry:

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

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

### Příklad:

##### V Basicu

V následujícím příkladu se vestavěnou funkcí DimArray vytvoří pole a to se poté uloží do buňky "A1":

        Dim arrData as Variant
        arrData = DimArray(2, 1)
        arrData(0, 0) = 1 : arrData(1, 0) = 2 : arrData(2, 0) = 3
        arrData(0, 1) = "One" : arrData(1, 1) = "Two" : arrData(2, 1) = "Three"
        oDoc.SetArray("Sheet1.A1", arrData)

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

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

##### V Pythonu

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

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

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

## SetValue

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

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

### Syntaxe:

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

### Parametry:

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

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

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

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

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

### Příklad:

##### V Basicu

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

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

        Dim firstCell As String : firstCell = "A1"
        Dim lenArray As Integer : lenArray = UBound(arrData) - LBound(arrData) + 1
        Dim newRange As String : newRange = oDoc.Offset(firstCell, width = lenArray)
        oDoc.SetValue(newRange, arrData)

##### V Pythonu

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

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

## SetCellStyle

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

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

### Syntaxe:

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

### Parametry:

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

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

### Příklad:

##### V Basicu

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

##### V Pythonu

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

## SetFormula

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

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

### Syntaxe:

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

### Parametry:

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

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

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

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

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

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

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

### Příklad:

##### V Basicu

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

##### V Pythonu

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

## SortRange

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

### Syntaxe:

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

### Parametry:

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

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

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

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

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

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

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

### Příklad:

##### V Basicu

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

##### V Pythonu

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

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.

Související témata

Služba SFDocuments.Document

Služba ScriptForge.UI