Nápověda LibreOfficeDev 7.6
Služba UI (user interface, uživatelské rozhraní) zjednodušuje identifikování a manipulace s různými okny, ze kterých se skládá celá aplikace LibreOfficeDev.
výběr oken
přesun a změna velikosti oken
nastavení stavového řádku
zobrazení plovoucího ukazatele průběhu
vytváření nových oken
přístup k souvisejícím dokumentům
Služba UI je výchozím bodem, pokud chcete z uživatelského skriptu otevírat stávající dokumenty, vytvářet nové nebo přistupovat k jejich obsahu.
Okno může být určeno různými způsoby:
úplnou cestou a názvem souboru
poslední částí úplného názvu souboru, nebo dokonce pouze poslední částí bez přípony
název okna
u nových dokumentů označení jako "Bez názvu 1"
některé ze speciálních oken "BASICIDE" a "WELCOMESCREEN"
U názvu okna se rozlišuje velikost písmen.
Níže popsané metody CreateDocument, CreateBaseDocument, GetDocument,OpenBaseDocument a OpenDocument vytvářejí objekty dokumentů. Pokud okno obsahuje dokument, je tento dokument reprezentován instancí třídy Document. Opačným případem je IDE jazyka Basic, které není dokumentem, ale pouze oknem. Dokument má také typ: Calc, Impress, Writer, ...
Specifické vlastnosti a metody použitelné na dokumenty jsou implementovány v třídě dokumentu.
Třídy s objekty dokumentů jsou implementovány v související knihovně SFDocuments (viz její službu Document).
Před používáním služby UI je nutné načíst či naimportovat knihovnu ScriptForge pomocí:
    Dim ui As Variant
    GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
    Set ui = CreateScriptService("UI")
  
    from scriptforge import CreateScriptService
    ui = CreateScriptService("UI")
  | Název | Pouze pro čtení | Typ | Popis | 
|---|---|---|---|
| ActiveWindow | ano | String | Platný a jedinečný název WindowName pro aktuálně aktivní okno. Jestliže okno nelze identifikovat, vrátí se řetězec s nulovou délkou. | 
| Documents | ano | String array | Seznam aktuálně otevřených dokumentů. Speciální okna jsou ignorována. Seznam se skládá z jednorozměrného pole začínajícího od 0 s názvy souborů (v zápisu SF_FileSystem.FileNaming) nebo s názvy oken u neuložených dokumentů. | 
| Height | ano | Integer | Vrátí výšku aktivního okna v pixelech. | 
| Width | ano | Integer | Vrátí šířku aktivního okna v pixelech. | 
| X | ano | Integer | Vrátí v pixelech souřadnici X aktivního okna, tj. jeho vzdálenost od levého okraje obrazovky. | 
| Y | ano | Integer | Vrátí v pixelech souřadnici Y aktivního okna, tj. jeho vzdálenost od horního okraje obrazovky. V této hodnotě nejsou zahrnuty prvky okna přidávané operačním systém, a proto ani u maximalizovaného okna tato hodnota nemusí být nula. | 
| Název | Hodnota | Popis | 
|---|---|---|
| MACROEXECALWAYS | 2 | Makra jsou vždy spouštěna. | 
| MACROEXECNEVER | 1 | Makra nejsou nikdy spouštěna. | 
| MACROEXECNORMAL | 0 | Spouštění maker závisí na uživatelském nastavení. | 
V následujícím příkladu se zobrazí okno MsgBox s názvy všech aktuálně otevřených dokumentů.
      Dim openDocs as Object, strDocs as String
     Set openDocs = ui.Documents()
     strDocs = openDocs(0)
     For i = 1 to UBound(openDocs)
         strDocs = strDocs & Chr(10) & openDocs(i)
     Next i
     MsgBox strDocs
   
     ui = CreateScriptService("UI")
     bas = CreateScriptService("Basic")
     openDocs = ui.Documents()
     strDocs = "\n".join(openDocs)
     bas.MsgBox(strDocs)
   | Seznam metod služby UI | ||
|---|---|---|
| 
           Activate | ||
Jako výjimky jsou hvězdičkou (*) označeny metody, které nejsou použitelné na dokumenty aplikace Base.
Aktivuje určené okno. Metoda vrátí True, pokud je zadané okno nalezeno a lze jej aktivovat. Jestliže výběru žádné okno neodpovídá, v uživatelském rozhraní se nic nezmění.
svc.Activate(windowname: str): bool
windowname: viz výše uvedené definice.
      ui.Activate("C:\Documents\My file.odt")
    
      ui.Activate(r"C:\Documents\My file.odt")
    Vytvoří a uloží nový dokument LibreOfficeDev Base s vloženou prázdnou databází zadaného typu. Metoda vrátí instanci služby Document.
svc.CreateBaseDocument(filename: str, embeddeddatabase: str = 'HSQLDB', registrationname: str = '', opt calcfilename: str): svc
filename: Určuje soubor, který se má vytvořit. Název musí odpovídat zápisu SF_FileSystem.FileNaming. Pokud již soubor existuje, je bez upozornění přepsán.
embeddeddatabase: Některá z možností "HSQLDB" (výchozí), "FIREBIRD" nebo "CALC".
registrationname: Název použitý pro uložení nové databáze v registru databází. Pokud je "" (výchozí), databáze se nezaregistruje. Pokud již název existuje, je bez upozornění přepsán.
calcfilename: Pouze pro možnost embeddeddatabase = "CALC". Představuje název souboru obsahujícího tabulky v podobě listů Calcu. Pokud soubor neexistuje, nastane chyba.
      Dim myBase As Object, myCalcBase As Object
      Set myBase = ui.CreateBaseDocument("C:\Databases\MyBaseFile.odb", "FIREBIRD")
      Set myCalcBase = ui.CreateBaseDocument("C:\Databases\MyCalcBaseFile.odb", _
          "CALC", , "C:\Databases\MyCalcFile.ods")
   
     myBase = ui.CreateBaseDocument(r"C:\Databases\MyBaseFile.odb", "FIREBIRD")
     myCalcBase = ui.CreateBaseDocument(r"C:\Databases\MyCalcBaseFile.odb", \
         "CALC", calcfilename = r"C:\Databases\MyCalcFile.ods")
   Vytvoří nový dokument LibreOfficeDev zadaného typu nebo ze zadané šablony. Metoda vrátí objekt dokumentu.
svc.CreateDocument(documenttype: str = '', templatefile: str = '', hidden: bool = False): svc
documenttype: "Calc", "Writer" atd. Není-li tento argument zadán, je nutné zadat argument templatefile.
templatefile: Úplný název FileName šablony, ze které se má nový dokument vytvořit. Pokud soubor neexistuje, tento argument je ignorován. Při vytváření tohoto argumentu je možné použít vlastnosti TemplatesFolder a UserTemplatesFolder služby FileSystem.
hidden: Je-li True, nový dokument se otevře na pozadí (výchozí = False). Používejte tuto možnost obezřetně: takový dokument je možné aktivovat nebo zavřít pouze programem.
V obou níže uvedených příkladech je pomocí metody CreateDocument nejprve vytvořen prázdný dokument Calcu, její druhé volání vytvoří dokument ze souboru šablony.
      Dim myDoc1 As Object, myDoc2 As Object, FSO As Object
      Set myDoc1 = ui.CreateDocument("Calc")
      Set FSO = CreateScriptService("FileSystem")
      Set myDoc2 = ui.CreateDocument(, FSO.BuildPath(FSO.TemplatesFolder, "personal/CV.ott"))
   
     myDoc1 = ui.CreateDocument("Calc")
     fs = CreateScriptService("FileSystem")
     myDoc2 = ui.CreateDocument(templatefile = fs.BuildPath(fs.TemplatesFolder, "personal/CV.ott"))
   Vrátí objekt otevřeného dokumentu odkazující na aktivní okno, na zadané okno nebo na aktivní dokument.
svc.GetDocument(windowname: str = ''): svc
svc.GetDocument(windowname: uno): svc
windowname: Viz výše uvedené definice. Není-li tento argument zadán, použije se aktivní okno. Zadat lze také objekty UNO typu com.sun.star.lang.XComponent nebo com.sun.star.comp.dba.ODatabaseDocument. Zadání objektu ThisComponent nebo ThisDatabaseDocument vytvoří novou službu SFDocuments.Document, Base či Calc.
      Dim myDoc As Object
      Set myDoc = ui.GetDocument("C:\Documents\My file.odt")
      Set myBase = ui.GetDocument(ThisDatabaseDocument)
   
     from scriptforge import CreateScriptService
     bas = CreateScriptService("Basic")
     myDoc = ui.GetDocument(r"C:\Documents\My file.odt")
     myDoc = ui.GetDocument(bas.ThisComponent)
   Chcete-li získat název aktuálně aktivního okna, použijte vlastnost ActiveWindow.
Maximalizuje aktivní nebo zadané okno.
svc.Maximize(windowname: str)
windowname: viz výše uvedené definice. Není-li tento argument zadán, je maximalizováno aktivní okno.
      ui.Maximize("Untitled 1")
   
     ui.Maximize("Untitled 1")
   Minimalizuje aktivní nebo zadané okno.
svc.Minimize(windowname: str)
windowname: viz výše uvedené definice. Není-li tento argument zadán, je minimalizováno aktivní okno.
     ui.Minimize()
   
     ui.Minimize()
   Otevře existující dokument LibreOfficeDev Base. Metoda vrátí objekt dokumentu.
svc.OpenBaseDocument(filename: str = '', registrationname: str = '', macroexecution: int = 0): svc
filename: Urč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.
macroexecution: 0 = chování je určeno nastavením uživatele, 1 = makra nejsou spustitelná, 2 = makra jsou spustitelná.
      Dim myBase As Object
      Set myBase = ui.OpenBaseDocument("C:\Documents\myDB.odb", MacroExecution := ui.MACROEXECALWAYS)
   
     ui.OpenBaseDocument(r"C:\Documents\myDB.odb", macroexecution = ui.MACROEXECALWAYS)
   To improve code readability you can use predefined constants for the macroexecution argument, as in the examples above.
Otevře existující dokument LibreOfficeDev se zadanými možnostmi. Vrátí objekt dokumentu nebo některou z jeho podtříd. Jestliže otevírání selže (a to i když je selhání způsobeno rozhodnutím uživatele), metoda vrátí Nothing (v Basicu) nebo None (v Pythonu).
svc.Opendocument(filename: str, password: str = '', readonly: bool = False, hidden: bool = False, macroexecution: int = 0, filtername: str = '', filteroptions: str = ''): svc
filename: Určuje soubor, který se má otevřít. Musí odpovídat zápisu FileNaming služby FileSystem.
password: Používá se v případě, že je dokument chráněn heslem. Je-li heslo chybné nebo není zadáno a dokument je chráněn, k zadání hesla bude uživatel vyzván.
readonly: Výchozí = False.
hidden: Je-li True, nový dokument se otevře na pozadí (výchozí = False). Používejte tuto možnost obezřetně: takový dokument je možné aktivovat nebo zavřít pouze programem.
macroexecution: 0 = chování je určeno nastavením uživatele, 1 = makra nejsou spustitelná, 2 = makra jsou spustitelná.
filtername: Název filtru, který by se měl pro načtení dokumentu použít. Je-li zadán, filtr musí existovat.
filteroptions: Nepovinný řetězec možností pro zadaný filtr.
      Dim myDoc As Object, FSO As Object
      Set myDoc = ui.OpenDocument("C:\Documents\myFile.odt", ReadOnly := True)
   
     ui.OpenDocument(r"C:\Documents\myFile.odt", readonly = True)
   Změní velikost aktivního okna a/nebo jej přesune. Nezadané a záporné argumenty jsou ignorovány. Jestliže je okno minimalizováno či maximalizováno, volání metody Resize bez argumentů jej obnoví.
svc.Resize(left: int = -1, top: int = -1, width: int = -1, height: int = -1)
left, top: Vzdálenosti levého horního rohu od horního a levého okraje obrazovky (v pixelech).
width, height: Nové rozměry okna (v pixelech).
V následujících příkladech je u okna změněna šířka width a výška height, zatímco vzdálenost shora top a zleva left je ponechána beze změny.
      ui.Resize(, ,500, 500)
   
     ui.Resize(width = 500, height = 500)
   Chcete-li změnit velikost neaktivního okna, nejprve jej aktivujte metodou Activate.
Spustí pro aktuální okno příkaz UNO. Typickými příkazy jsou: Save, SaveAs, ExportToPDF, Undo, Copy, Paste atd.
Příkazy lze spouštět s argumenty nebo bez nich. Přes spuštěním příkazu se argumenty nekontrolují. Pokud je příkaz nebo jeho argumenty neplatné, nic se neprovede.
Úplný seznam příkazů UNO, které lez v LibreOfficeDev spouštět, naleznete na wiki stránce Development/DispatchCommands.
svc.RunCommand(command: str, [args: any])
command: Řetězec, u něhož se rozlišuje velikost písmen, obsahující název příkazu UNO. Předpona ".uno:" je v názvu příkazu nepovinná. Nekontroluje se správnost příkazu. Jestliže se po zavolá příkazu nic nestane, je pravděpodobně chybný.
args: Pro každý argument, který se má příkazu předat, určete dvojici udávající název a hodnotu argumentu.
V následujícím příkladu se v aktuálním okně spustí příkaz .uno:About.
    Set ui = CreateScriptService("UI")
    ui.RunCommand("About")
  V příkladu níže se spustí příkaz UNO .uno:BasicIDEAppear a předají se mu argumenty, které určují, aby se IDE jazyka Basic otevřelo na stanoveném řádku zadaného modulu.
    ' Argumenty předané příkazu:
    ' Document  = "LibreOffice Macros & Dialogs"
    ' LibName = "ScriptForge"
    ' Name = "SF_Session"
    ' Line = 600
    ui.RunCommand(".uno:BasicIDEAppear", "Document", "LibreOffice Macros & Dialogs", _ 
                  "LibName", "ScriptForge", "Name", "SF_Session", "Line", 600)
  Volání příkazu BasicIDEAppear bez argumentů IDE jazyka Basic pouze otevře.
    ui = CreateScriptService("UI")
    ui.RunCommand("About")
  
    ui.RunCommand(".uno:BasicIDEAppear", "Document", "LibreOffice Macros & Dialogs", \
                  "LibName", "ScriptForge", "Name", "SF_Session", "Line", 600)
  V Pythonu je možné při volání metody RunCommand použít názvy argumentů:
    ui.RunCommand(".uno:BasicIDEAppear", Document = "LibreOffice Macros & Dialogs", \
                  LibName = "ScriptForge", Name = "SF_Session", Line = 600)
  Sada dostupných příkazů závisí na používané komponentě LibreOfficeDev. Jednoduchým způsobem, jak příkazy zjistit, je přejít na Nástroje - Přizpůsobit - Klávesnice. Umístíte-li myš nad funkci v seznamu Funkce, zobrazí se tip s příslušným příkazem UNO.
Zobrazí ve stavovém řádku aktivního okna text a ukazatel průběhu. Jakékoliv další volání v témže makru bude odkazovat na tentýž stavový řádek téhož okna, i když okno už nebude viditelné. Volání metody bez argumentů obnoví běžný stav stavového řádku.
svc.SetStatusbar(text: str = '', percentage: int = -1)
text: Nepovinný text, který se má zobrazit v popředí ukazatele průběhu.
percentage: nepovinný stupeň průběhu mezi 0 a 100.
      Dim i As Integer
      For i = 0 To 100
          ui.SetStatusbar("Progress ...", i)
          Wait 50
      Next i
      ' Obnoví stavový řádek
      ui.SetStatusbar
   
     from time import sleep
     for i in range(101):
         ui.SetStatusbar("Test:", i)
         sleep(0.05)
     ui.SetStatusbar()
   Zobrazí nemodální dialogové okno, pro nějž určíte název, vysvětlující text a procento průběhu, které se má zobrazit ukazatelem průběhu. Dialogové okno zůstane zobrazené, dokud nezavoláte tuto metodu bez argumentů nebo dokud uživatel okno nezavře ručně.
svc.ShowProgressBar(title: str = '', text: str = '', percentage: str = -1)
title : Název zobrazený v záhlaví dialogového okna. Výchozí = "ScriptForge".
text: Nepovinný text, který se má zobrazit nad ukazatelem průběhu.
percentage: nepovinný stupeň průběhu mezi 0 a 100.
      Dim i As Integer
      For i = 0 To 100
          ui.ShowProgressBar("Window Title", "Progress ..." & i & "/100", i)
          Wait 50
      Next i
      ' Zavře okno s ukazatelem průběhu
      ui.ShowProgressBar
   
     from time import sleep
     for i in range(101):
         ui.ShowProgressBar("Window Title", "Progress ... " + str(i) + "/100", i)
         sleep(0.05)
     # Zavře okno s ukazatelem průběhu
     ui.ShowProgressBar()
   Vrátí True, pokud lze zadané okno identifikovat.
svc.WindowExists(windowname: str): bool
windowname: viz výše uvedené definice.
      If ui.WindowExists("C:\Document\My file.odt") Then
          ' ...
   
     if ui.WindowExists(r"C:\Document\My file.odt"):
         # ...