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
Pojmenovaná sada schopností. Říká, jaké vlastnosti a rozhraní objekt má. Např. com.sun.star.sheet.SpreadsheetDocument.
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í.
Konkrétní instance. Získáš ji z jiného objektu nebo ze služby. Může implementovat více služeb a rozhraní najednou.
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ázev | Význam |
|---|---|
StarDesktop | Služba com.sun.star.frame.Desktop |
ThisComponent | Dokument, ze kterého je makro spuštěno (nikoli samotné Basic IDE) |
ThisDatabaseDocument | Dokument Base, pokud je makro uloženo v něm |
GlobalScope | Pří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 = 42Otevř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řítUlož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 IfZkoumá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žba | K čemu slouží |
|---|---|
com.sun.star.frame.Desktop | Otevírání, správa oken a dokumentů |
com.sun.star.sheet.FunctionAccess | Volání funkcí Calcu z Basicu |
com.sun.star.ui.dialogs.FilePicker | Dialog pro výběr souboru |
com.sun.star.ui.dialogs.FolderPicker | Dialog pro výběr složky |
com.sun.star.util.PathSubstitution | Proměnné cest ($(home), $(user)) |
com.sun.star.util.PathSettings | Nastavené cesty aplikace (šablony, záloha…) |
com.sun.star.awt.Toolkit | Nízkoúrovňové GUI, např. vlastní okna |
com.sun.star.sdb.DatabaseContext | Registrované databáze |
com.sun.star.system.SystemShellExecute | Spouštění externích programů |
com.sun.star.util.NumberFormatter | Formátování čísel a dat |
com.sun.star.i18n.CharacterClassification | Práce s velikostí písmen a třídami znaků |
com.sun.star.beans.PropertyValue | Struktura 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 = TruePomocná 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 SubPoslední použitý řádek
oCursor = oSheet.createCursor()
oCursor.gotoEndOfUsedArea(False)
nPosledniRadek = oCursor.RangeAddress.EndRow ' od nulyPro 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 SubHledá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 FunctionDialog 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 SubBase 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 SubV 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
loadComponentFromURLastoreToURLpatřífile:///C:/…, protoConvertToURL. - Správná vlastnost buňky.
.Stringje text,.Valuečíslo,.Formulavzorec. Zápis čísla do.Stringvytvoří textovou buňku. - „Property or method not found“. Objekt je jiného typu, než čekáš. Zkontroluj
dbg_methodsadbg_supportedInterfaces. ThisComponentv IDE. Funguje správně, i když je otevřený editor maker, aleStarDesktop.CurrentComponentby tam vrátilo samotné IDE.- Uvolňování. Dialogy ukonči
dispose(), databázová spojení zavírejclose(). - 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.