Služba ScriptForge.UI

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

tip

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.


Definice

WindowName

Okno může být určeno různými způsoby:

U názvu okna se rozlišuje velikost písmen.

Objekt dokumentu

Níže popsané metody CreateDocument, CreateBaseDocument, GetDocument 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.

tip

Třídy s objekty dokumentů jsou implementovány v související knihovně SFDocuments (viz její službu Document).


Volání služby

V Basicu

    Dim ui As Variant
    GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
    Set ui = CreateScriptService("UI")
  
V Pythonu

    from scriptforge import CreateScriptService
    ui = CreateScriptService("UI")
  

Vlastnosti

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


Konstanty

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


Příklad:

V následujícím příkladu se zobrazí okno MsgBox s názvy všech aktuálně otevřených dokumentů.

V Basicu

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

     ui = CreateScriptService("UI")
     bas = CreateScriptService("Basic")
     openDocs = ui.Documents()
     strDocs = "\n".join(openDocs)
     bas.MsgBox(strDocs)
   

Seznam metod služby UI

Activate
CreateBaseDocument
CreateDocument (*)
GetDocument

Maximize
Minimize
OpenBaseDocument
OpenDocument (*)

Resize
SetStatusBar (*)
ShowProgressBar
WindowExists


warning

Jako výjimky jsou hvězdičkou (*) označeny metody, které nejsou použitelné na dokumenty aplikace Base.


Activate

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

Syntaxe:

svc.Activate(windowname: str): bool

Parametry:

windowname: viz výše uvedené definice.

Příklad:

V Basicu

      ui.Activate("C:\Documents\My file.odt")
    
V Pythonu

      ui.Activate(r"C:\Documents\My file.odt")
    

CreateBaseDocument

Vytvoří a uloží nový dokument LibreOffice Base s vloženou prázdnou databází zadaného typu. Metoda vrátí instanci služby Document.

Syntaxe:

svc.CreateBaseDocument(filename: str, embeddeddatabase: str = 'HSQLDB', registrationname: str = '', opt calcfilename: str): svc

Parametry:

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.

Příklad:

V Basicu

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

     myBase = ui.CreateBaseDocument(r"C:\Databases\MyBaseFile.odb", "FIREBIRD")
     myCalcBase = ui.CreateBaseDocument(r"C:\Databases\MyCalcBaseFile.odb", \
         "CALC", calcfilename = r"C:\Databases\MyCalcFile.ods")
   

CreateDocument (*)

Vytvoří nový dokument LibreOffice zadaného typu nebo ze zadané šablony. Metoda vrátí objekt dokumentu.

Syntaxe:

svc.CreateDocument(documenttype: str = '', templatefile: str = '', hidden: bool = False): svc

Parametry:

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.

Příklad:

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.

V Basicu

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

     myDoc1 = ui.CreateDocument("Calc")
     FSO = CreateScriptService("FileSystem")
     myDoc2 = ui.CreateDocument(templatefile = FSO.BuildPath(FSO.TemplatesFolder, "personal/CV.ott"))
   

GetDocument

Vrátí objekt dokumentu odkazující na aktivní okno, na zadané okno nebo na aktivní dokument.

Syntaxe:

svc.GetDocument(windowname: str = ''): svc

svc.GetDocument(windowname: uno): svc

Parametry:

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.

Příklad:

V Basicu

      Dim myDoc As Object
      Set myDoc = ui.GetDocument("C:\Documents\My file.odt")
      Set myBase = ui.GetDocument(ThisDatabaseDocument)
   
V Pythonu

     myDoc = ui.GetDocument(r"C:\Documents\My file.odt")
     from scriptforge import CreateScriptService
     bridge = CreateScriptService("Basic")
     myDoc = ui.GetDocument(bridge.ThisComponent)
   
tip

Chcete-li získat název aktuálně aktivního okna, použijte vlastnost ActiveWindow.


Maximize

Maximalizuje aktivní nebo zadané okno.

Syntaxe:

svc.Maximize(windowname: str)

Parametry:

windowname: viz výše uvedené definice. Není-li tento argument zadán, je maximalizováno aktivní okno.

Příklad:

V Basicu

      ui.Maximize("Untitled 1")
   
V Pythonu

     ui.Maximize("Untitled 1")
   

Minimize

Minimalizuje aktivní nebo zadané okno.

Syntaxe:

svc.Minimize(windowname: str)

Parametry:

windowname: viz výše uvedené definice. Není-li tento argument zadán, je minimalizováno aktivní okno.

Příklad:

V Basicu

     ui.Minimize()
   
V Pythonu

     ui.Minimize()
   

OpenBaseDocument

Otevře existující dokument LibreOffice Base. Metoda vrátí objekt dokumentu.

Syntaxe:

svc.OpenBaseDocument(filename: str = '', registrationname: str = '', macroexecution: int = 0): svc

Parametry:

filename: Určuje soubor, který se má otevřít. Název musí odpovídat zápisu SF_FileSystem.FileNaming. Pokud již soubor existuje, je bez upozornění přepsán.

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

Příklad:

V Basicu

      Dim myBase As Object
      Set myBase = ui.OpenBaseDocument("C:\Documents\myDB.odb", MacroExecution := ui.MACROEXECALWAYS)
   
V Pythonu

     ui.OpenBaseDocument(r"C:\Documents\myDB.odb", macroexecution = ui.MACROEXECALWAYS)
   
tip

V zájmu čitelnějšího kódu můžete pro argument macroexecution použít předdefinované konstanty jako ve výše uvedených příkladech.


OpenDocument (*)

Otevře existující dokument LibreOffice 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).

Syntaxe:

svc.Opendocument(filename: str, password: str = '', readonly: bool = False, hidden: bool = False, macroexecution: int = 0, filtername: str = '', filteroptions: str = ''): svc

Parametry:

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.

Příklad:

V Basicu

      Dim myDoc As Object, FSO As Object
      Set myDoc = ui.OpenDocument("C:\Documents\myFile.odt", ReadOnly := True)
   
V Pythonu

     ui.OpenDocument(r"C:\Documents\myFile.odt", readonly = True)
   

Resize

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

Syntaxe:

svc.Resize(left: int = -1, top: int = -1, width: int = -1, height: int = -1)

Parametry:

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

Příklad:

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.

V Basicu

      ui.Resize(, ,500, 500)
   
V Pythonu

     ui.Resize(width = 500, height = 500)
   
tip

Chcete-li změnit velikost neaktivního okna, nejprve jej aktivujte metodou Activate.


SetStatusbar (*)

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.

Syntaxe:

svc.SetStatusbar(text: str = '', percentage: int = -1)

Parametry:

text: Nepovinný text, který se má zobrazit v popředí ukazatele průběhu.

percentage: nepovinný stupeň průběhu mezi 0 a 100.

Příklad:

V Basicu

      Dim i As Integer
      For i = 0 To 100
          ui.SetStatusbar("Progress ...", i)
          Wait 50
      Next i
      ' Obnoví stavový řádek
      ui.SetStatusbar
   
V Pythonu

     from time import sleep
     for i in range(101):
         ui.SetStatusbar("Test:", i)
         sleep(0.05)
     ui.SetStatusbar()
   

ShowProgressBar

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

Syntaxe:

svc.ShowProgressBar(title: str = '', text: str = '', percentage: str = -1)

Parametry:

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.

Příklad:

V Basicu

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

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

WindowExists

Vrátí True, pokud lze zadané okno identifikovat.

Syntaxe:

svc.WindowExists(windowname: str): bool

Parametry:

windowname: viz výše uvedené definice.

Příklad:

V Basicu

      If ui.WindowExists("C:\Document\My file.odt") Then
          ' ...
   
V Pythonu

     if ui.WindowExists(r"C:\Document\My file.odt"):
         # ...