Rozhraní, objekty a služby v LibreOffice Basicu

Všechno, s čím v makrech pracuješ (dokument, list, buňka, odstavec, dialog), je objekt modelu UNO. Tahle příručka vysvětluje, jak spolu služby, rozhraní a objekty souvisí a jak je v Basicu používat.

Základní pojmy

Služba (service)

Pojmenovaná sada schopností. Říká, jaké vlastnosti a rozhraní objekt má. Např. com.sun.star.sheet.SpreadsheetDocument.

Rozhraní (interface)

Skupina souvisejících metod, např. XCellRange nebo XText. Názvy začínají písmenem X. V Basicu je voláš přímo, bez přetypování.

Objekt

Konkrétní instance. Získáš ji z jiného objektu nebo ze služby. Může implementovat více služeb a rozhraní najednou.

Vlastnost (property)

Datová položka objektu, např. oCell.String nebo oCell.CellBackColor. Technicky jde o rozhraní XPropertySet.

Vztah je takový: objekt implementuje jednu nebo více služeb, každá služba zahrnuje určitá rozhraní a vlastnosti. Pokud metoda v Basicu „neexistuje“, objekt příslušné rozhraní prostě nepodporuje.

Získání objektů

Služby a globální objekty

' Vytvoření služby podle jména
oDesktop = createUnoService("com.sun.star.frame.Desktop")

' Správce služeb celého procesu
oSM = GetProcessServiceManager()
oSluzba = oSM.createInstance("com.sun.star.sheet.FunctionAccess")

Zkratky, které Basic nabízí rovnou:

NázevVýznam
StarDesktopSlužba com.sun.star.frame.Desktop
ThisComponentDokument, ze kterého je makro spuštěno (nikoli samotné Basic IDE)
ThisDatabaseDocumentDokument Base, pokud je makro uloženo v něm
GlobalScopePřístup k aplikačním knihovnám (GlobalScope.BasicLibraries)

Dokument a jeho části

oDoc = ThisComponent                    ' makro uložené v dokumentu
oDoc = StarDesktop.CurrentComponent     ' právě aktivní dokument

' Calc
oSheet = oDoc.Sheets.getByIndex(0)
oCell  = oSheet.getCellByPosition(0, 0)   ' A1
oCell.String = "Ahoj"
oCell.Value  = 42

Otevření a uložení dokumentu

Dim aProps(0) As New com.sun.star.beans.PropertyValue
aProps(0).Name  = "Hidden"
aProps(0).Value = True

oDoc = StarDesktop.loadComponentFromURL( _
    ConvertToURL("C:\test.ods"), "_blank", 0, aProps())

oDoc.store()                  ' uložit
oDoc.close(True)              ' zavřít

Uložení do jiného formátu (např. PDF) se řídí filtrem:

Dim aF(0) As New com.sun.star.beans.PropertyValue
aF(0).Name  = "FilterName"
aF(0).Value = "calc_pdf_Export"        ' u Writeru "writer_pdf_Export"
oDoc.storeToURL(ConvertToURL("C:\vystup.pdf"), aF())

Zjištění typu dokumentu

If oDoc.supportsService("com.sun.star.sheet.SpreadsheetDocument") Then
    ' Calc
ElseIf oDoc.supportsService("com.sun.star.text.TextDocument") Then
    ' Writer
ElseIf oDoc.supportsService("com.sun.star.drawing.DrawingDocument") Then
    ' Draw
ElseIf oDoc.supportsService("com.sun.star.presentation.PresentationDocument") Then
    ' Impress
ElseIf oDoc.supportsService("com.sun.star.sdb.OfficeDatabaseDocument") Then
    ' Base
End If

Zkoumání objektů (introspekce)

MsgBox oCell.dbg_methods              ' seznam metod
MsgBox oCell.dbg_properties           ' seznam vlastností
MsgBox oCell.dbg_supportedInterfaces  ' implementovaná rozhraní
MsgBox oCell.getImplementationName()
MsgBox Join(oCell.getSupportedServiceNames(), Chr(10))

Pro pohodlnější zkoumání existují rozšíření MRI a XRay. S XRay stačí zavolat Xray oCell a zobrazí se strom vlastností, metod a rozhraní. Oficiální reference API je na api.libreoffice.org (IDL reference).

Přehled užitečných služeb

SlužbaK čemu slouží
com.sun.star.frame.DesktopOtevírání, správa oken a dokumentů
com.sun.star.sheet.FunctionAccessVolání funkcí Calcu z Basicu
com.sun.star.ui.dialogs.FilePickerDialog pro výběr souboru
com.sun.star.ui.dialogs.FolderPickerDialog pro výběr složky
com.sun.star.util.PathSubstitutionProměnné cest ($(home), $(user))
com.sun.star.util.PathSettingsNastavené cesty aplikace (šablony, záloha…)
com.sun.star.awt.ToolkitNízkoúrovňové GUI, např. vlastní okna
com.sun.star.sdb.DatabaseContextRegistrované databáze
com.sun.star.system.SystemShellExecuteSpouštění externích programů
com.sun.star.util.NumberFormatterFormátování čísel a dat
com.sun.star.i18n.CharacterClassificationPráce s velikostí písmen a třídami znaků
com.sun.star.beans.PropertyValueStruktura jméno–hodnota
' Spuštění externího programu
oShell = createUnoService("com.sun.star.system.SystemShellExecute")
oShell.execute("notepad.exe", "", 1)

' Cesta k uživatelské složce
oPS = createUnoService("com.sun.star.util.PathSubstitution")
sHome = oPS.substituteVariables("$(home)", True)

Struktury a pole PropertyValue

Mnoho metod očekává pole PropertyValue. Struktury se vytvářejí dvěma způsoby:

' 1) deklarace s New
Dim aBod As New com.sun.star.awt.Point
aBod.X = 100
aBod.Y = 200

' 2) funkce createUnoStruct
aBod = createUnoStruct("com.sun.star.awt.Point")

' Pole struktur
Dim aProps(1) As New com.sun.star.beans.PropertyValue
aProps(0).Name = "Hidden"   : aProps(0).Value = True
aProps(1).Name = "ReadOnly" : aProps(1).Value = True

Pomocná funkce, kterou si často napíšeš, vytvoří jednu hodnotu:

Function PV(sJmeno As String, vHodnota As Variant) As com.sun.star.beans.PropertyValue
    Dim p As New com.sun.star.beans.PropertyValue
    p.Name  = sJmeno
    p.Value = vHodnota
    PV = p
End Function

' použití
oDoc = StarDesktop.loadComponentFromURL(sURL, "_blank", 0, Array(PV("Hidden", True)))

Calc: buňky, oblasti, funkce

Sub CalcPrikladOblast()
    oSheet = ThisComponent.Sheets.getByName("List1")

    ' Oblast podle adresy
    oRange = oSheet.getCellRangeByName("A1:C3")

    ' Čtení a zápis celé oblasti najednou
    aData = oRange.getDataArray()          ' pole polí
    oRange.setDataArray(aData)

    ' Formát
    oRange.CellBackColor = RGB(220, 237, 243)
    oRange.CharWeight = com.sun.star.awt.FontWeight.BOLD

    ' Vzorec
    oSheet.getCellByPosition(3, 0).Formula = "=SUM(A1:C1)"
End Sub

Sub CalcFunkce()
    oFA = createUnoService("com.sun.star.sheet.FunctionAccess")
    nSoucet = oFA.callFunction("SUM", Array(1, 2, 3))
    MsgBox nSoucet
End Sub

Poslední použitý řádek

oCursor = oSheet.createCursor()
oCursor.gotoEndOfUsedArea(False)
nPosledniRadek = oCursor.RangeAddress.EndRow    ' od nuly

Pro velké objemy dat je mnohem rychlejší getDataArray / setDataArray než čtení a zápis po jednotlivých buňkách.

Writer: text, kurzor, odstavce

Sub WriterPriklad()
    oText   = ThisComponent.Text
    oCursor = oText.createTextCursor()

    oCursor.gotoEnd(False)
    oText.insertString(oCursor, "Nový odstavec", False)
    oText.insertControlCharacter(oCursor, _
        com.sun.star.text.ControlCharacter.PARAGRAPH_BREAK, False)
End Sub

' Průchod všemi odstavci
Sub ProjdiOdstavce()
    oEnum = ThisComponent.Text.createEnumeration()
    Do While oEnum.hasMoreElements()
        oPar = oEnum.nextElement()
        If oPar.supportsService("com.sun.star.text.Paragraph") Then
            Print oPar.String
        End If
    Loop
End Sub

Hledání a nahrazení

oDesc = ThisComponent.createReplaceDescriptor()
oDesc.SearchString  = "staré"
oDesc.ReplaceString = "nové"
oDesc.SearchCaseSensitive = False
nPocet = ThisComponent.replaceAll(oDesc)

Dialogy a výběr souboru

FilePicker

Function VyberSoubor() As String
    oDlg = createUnoService("com.sun.star.ui.dialogs.FilePicker")
    oDlg.setTitle("Vyber soubor")
    If oDlg.execute() = com.sun.star.ui.dialogs.ExecutableDialogResults.OK Then
        VyberSoubor = oDlg.getFiles()(0)    ' vrací URL
    End If
End Function

Dialog z editoru dialogů

Sub UkazDialog()
    DialogLibraries.LoadLibrary("Standard")
    oDlg = CreateUnoDialog(DialogLibraries.Standard.MujDialog)
    oDlg.getControl("TextField1").Text = "výchozí hodnota"
    If oDlg.execute() = 1 Then          ' 1 = OK
        sVysledek = oDlg.getControl("TextField1").Text
    End If
    oDlg.dispose()
End Sub

Base a databáze

Sub DotazDoDatabaze()
    oCtx = createUnoService("com.sun.star.sdb.DatabaseContext")
    oDB  = oCtx.getByName("MojeDatabaze")       ' registrovaný název
    oConn = oDB.getConnection("", "")

    oStmt = oConn.createStatement()
    oRes  = oStmt.executeQuery("SELECT ""Jmeno"" FROM ""Osoby""")
    Do While oRes.next()
        Print oRes.getString(1)                 ' sloupce od 1
    Loop

    oRes.close() : oStmt.close() : oConn.close()
End Sub

V SQL dotazech Base se názvy tabulek a sloupců dávají do uvozovek. V řetězci Basicu se zdvojují ("").

Funkce Basicu pro práci s UNO

FunkceÚčel
IsNull(obj)Zda je objekt prázdný (Nothing)
IsEmpty(var)Zda proměnná nebyla inicializována
HasUnoInterfaces(obj, "…XComponent")Zda objekt podporuje všechna zadaná rozhraní
EqualUnoObjects(a, b)Zda oba odkazy míří na stejný objekt
ConvertToURL(cesta)Cesta systému → URL (file:///…)
ConvertFromURL(url)URL → cesta systému
createUnoService(jmeno)Vytvoří službu
createUnoStruct(jmeno)Vytvoří strukturu
createUnoListener(prefix, rozhrani)Vytvoří posluchač událostí
createUnoDialog(…)Vytvoří dialog z knihovny dialogů

Proměnné držící UNO objekty deklaruj jako Object nebo Variant. Pro lepší čitelnost se používá maďarská notace: oDoc, oSheet, aProps (pole), sText, nPocet.

Časté chyby

  • Indexy jsou od nuly. getByIndex(0) je první list, getCellByPosition(0,0) je A1.
  • Cesty musí být URL. Do loadComponentFromURL a storeToURL patří file:///C:/…, proto ConvertToURL.
  • Správná vlastnost buňky. .String je text, .Value číslo, .Formula vzorec. Zápis čísla do .String vytvoří textovou buňku.
  • „Property or method not found“. Objekt je jiného typu, než čekáš. Zkontroluj dbg_methods a dbg_supportedInterfaces.
  • ThisComponent v IDE. Funguje správně, i když je otevřený editor maker, ale StarDesktop.CurrentComponent by tam vrátilo samotné IDE.
  • Uvolňování. Dialogy ukonči dispose(), databázová spojení zavírej close().
  • Velká a malá písmena. Basic je u názvů proměnných a procedur nerozlišuje, ale názvy služeb v řetězcích ("com.sun.star…") ano.