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

tip

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


Volání služby

Před používáním služby UI je nutné načíst či naimportovat knihovnu ScriptForge pomocí:

note

• V makrech Basicu je nutné načíst knihovnu ScriptForge následujícím příkazem:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Ve skriptech Pythonu je nezbytné import z modulu scriptforge:
from scriptforge import CreateScriptService


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.

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.


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 (*)
Documents
GetDocument

Maximize
Minimize
OpenBaseDocument
OpenDocument (*)
Resize

RunCommand
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í instanci třídy dokumentu nebo některé z jejích podtříd (Calc, Writer).

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")
     fs = CreateScriptService("FileSystem")
     myDoc2 = ui.CreateDocument(templatefile = fs.BuildPath(fs.TemplatesFolder, "personal/CV.ott"))
   

Documents

Seznam aktuálně otevřených dokumentů. Speciální okna jsou ignorováno. Seznam je představován jednorozměrným polem začínajícím od 0 obsahujícím buď názvy souborů v zápisu ScriptForge.FileSystem.FileNaming, nebo pro neuložené soubory název okna.

Syntaxe:

svc.Documents(): str[1..*]

Příklad:

V obou následujících příkladech metoda vrátí prázdné pole, pokud není otevřen žádný dokument.

V Basicu

      Dim docList As Variant
      docList = ui.Documents
   
V Pythonu

     docList = ui.Documents()
   

GetDocument

Vrátí instanci třídy Document nebo některé z jejích podtříd (Calc, Writer, Base, FormDocument), která představuje buď zadané okno, nebo 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

     from scriptforge import CreateScriptService
     bas = CreateScriptService("Basic")
     myDoc = ui.GetDocument(r"C:\Documents\My file.odt")
     myDoc = ui.GetDocument(bas.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 Base.

Syntaxe:

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

Parametry:

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á. Výchozí je 0.

Příklad:

V Basicu

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

     myBase = 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á. Výchozí je 0.

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

     myDoc = 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(Width := 500, Height := 500)
   
V Pythonu

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

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


RunCommand

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.

tip

Úplný seznam příkazů UNO, které lez v LibreOffice spouštět, naleznete na wiki stránce Development/DispatchCommands.


Syntaxe:

svc.RunCommand(command: str, [args: any])

Parametry:

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.

Příklad:

V Basicu

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.

V Pythonu

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

Sada dostupných příkazů závisí na používané komponentě LibreOffice. 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.


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: int = -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"):
         # ...
   

Podpořte nás!