Obsah

# 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

##### 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

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)

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)

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)

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.

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

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

Související témata

Služba ScriptForge.Basic

Služba SFDocuments.Calc

Služba SFDocuments.Document