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.

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

Definice

WindowName

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.

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.

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

• 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

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

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

Vlastnosti

Konstanty

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)
   

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

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

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.

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

CreateDocument (*)

Vytvoří nový dokument LibreOffice 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"))
   

GetDocument

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.

Maximize

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

Minimize

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

OpenBaseDocument

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

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

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)
   

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

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.

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.

Úplný seznam příkazů UNO, které lez v LibreOffice 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ě 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.

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

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

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

WindowExists

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