Vsebina

# Storitev ScriptForge.UI

Storitev UI (User Interface, angl. za uporabniški vmesnik) poenostavlja identifikacijo in ravnanje z različnimi okni, ki tvorijo celoten program LibreOffice:

- izbiranje oken;

- premikanje in spreminjanje oken;

- nastavitve vrstice stanja;

- prikaz plavajoče vrstice napredka;

- ustvarjanje novih oken;

- Dostop do osnovnih "dokumentov"

Storitev UI je začetna točka za odpiranje, ustvarjanje ali dostopanje do vsebine novih ali obstoječih dokumentov iz uporabniškega skripta.

## Definicije

### WindowName

Okno je lahko začasno imenovano na več načinov:

- s polno potjo in imenom datoteke;

- z zadnjo komponento polnega imena datoteke ali celo z zadnjo komponento brez končnice;

- z naslovom okna;

- za nove dokumente z nizom, kot je "Neimenovano 1";

- z enim od posebnih poken "BASICIDE" in "WELCOMESCREEN".

Pri imenih oken je pomembna velikost črk.

### Predmet dokumenta

Metode CreateDocument, CreateBaseDocument, GetDocument, OpenBaseDocument in OpenDocument, opisane v nadaljevanju, tvorijo predmete dokumenta. Če okno vsebuje dokument, instanca razreda Document predstavlja ta dokument. Nasprotno je v terminologiji Basic IDE, v okviru katere to ni dokument, temveč okno. Poleg tega je dokument določene vrste: Calc, Impress, Writer, ...

Specifične lastnosti in metode, namenjene dokumentom, so implementiranem v razredu dokumentov.

Implementacija razreda predmetov dokumenta se opravi v pridruženi knjižnici SFDocuments. Glejte njeno storitev "Document".

## Priklic storitve

Pred uporabo storitve UI je potrebno naložiti ali uvoziti knjižnico ScriptForge:

• Za makre Basic mora biti naložena knjižnica ScriptForge z naslednjim ukazom:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
• Za skripte Python mora biti opravljen uvoz iz modula 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")

## Lastnosti

Ime | Samo za branje | Vrsta | Opis
--- | --- | --- | ---
ActiveWindow | Da | String | Veljavno in enkratno ime WindowName za trenutno dejavno okno. Če okna ni mogoče identificirati, vrne niz ničelne dolžine.
Height | Da | Integer | Vrne višino dejavnega okna v slikovnih točkah.
Width | Da | Integer | Vrne širino dejavnega okna v slikovnih točkah.
X | Da | Integer | Vrne koordinato X dejavnega okna, ki predstavlja razdaljo do levega roba zaslona v slikovnih točkah.
Y | Da | Integer | Vrne koordinato Y dejavnega okna, ki predstavlja razdaljo do zgornjega roba zaslona v slikovnih točkah. Ta vrednost ne upošteva okrasitev oken, ki jih doda vaš operacijski sistem, tako da je tudi takrat, ko je okno povsem povečano, ta vrednost lahko enaka nič.

## Konstante

Ime | Vrednost | Opis
--- | --- | ---
MACROEXECALWAYS | 2 | Makri se vedno izvedejo
MACROEXECNEVER | 1 | Makri se nikoli ne izvedejo
MACROEXECNORMAL | 0 | Izvajanje makrov je odvisno od uporabniških nastavitev

### Primer:

Spodnji primer prikazuje MsgBox z imeni vseh trenutno odprtih dokumentov.

##### 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 storitve UI
Activate CreateBaseDocument CreateDocument (*) Documents GetDocument | Maximize Minimize OpenBaseDocument OpenDocument (*) Resize | RunCommand SetStatusBar (*) ShowProgressBar WindowExists

Upoštevajte izjemo, da metod, označenih z (*), ni mogoče uporabiti z dokumenti Base.

## Activate

Naredi navedeno okno dejavno. Metoda vrne True, če je dano okno najdeno in ga je možno aktivirati. Če nobeno okno ne ustreza izboru, v dejanskem uporabniškem vmesniku ni spremembe.

### Skladnja:

svc.Activate(windowname: str): bool

### Parametri:

windowname: glejte zgornje definicije.

### Primer:

##### V Basicu

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

##### V Pythonu

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

## CreateBaseDocument

Ustvari in shrani nov dokument LibreOffice Base, ki vdela prazno zbirko podatkov dane vrste. Metoda vrne instanco storitve Document.

### Skladnja:

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

### Parametri:

filename: ime datoteke, ki jo želite ustvariti. Slediti mora obliki zapisa SF_FileSystem.FileNaming. Če datoteka že obstaja, bo prepisana brez opozorila.

embeddeddatabase: možne vrste vdelane zbirke podatkov so "HSQLDB" (privzeto), "FIREBIRD" in "CALC".

registrationname: ime, uporabljeno za hrambo nove zbirke podatkov v registru zbirk podatkov. Ko je enako "" (privzeta vrednost), ime ne bo registrirano. Če ime že obstaja, je brez opozorila prepisano.

calcfilename: samo ko ima parameter embeddeddatabase vrednost "CALC", predstavlja calcfilename datoteko, ki vsebuje tabele kot delovne liste datoteke programa Calc. Datoteka mora obstajati, sicer javi napako.

### Primer:

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

Ustvari nov dokument LibreOffice dane vrste ali na osnovi dane predloge. Metoda vrne instanco razreda dokumenta ali enega od njegovih podrazredov (Calc, Writer).

### Skladnja:

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

### Parametri:

documenttype: vrsta dokumenta, kot npr. "Calc", "Writer" itn. Če ni naveden, mora biti prisoten argument templatefile.

templatefile: polno ime predloge FileName, na temelju katere bo izdelan dokument. Če datoteka ne obstaja, je argument prezrt. Storitev FileSystem zagotavlja lastnosti TemplatesFolder in UserTemplatesFolder, ki sta v pomoč pri izdelavi argumenta.

hidden: če je True, odpre nov dokument v ozadju (privzeto = False). Pozor pri uporabi: kasnejša aktivacija in zapiranje se lahko izvedeta samo programsko.

### Primer:

V obeh spodnjih primerih prvi klic metode CreateDocument ustvari prazen dokument programa Calc, medtem ko drugi ustvari dokument iz datoteke predloge.

##### 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 trenutno odprtih dokumentov. Posebna okna so prezrta. Ta seznam sestavlja na ničlah temelječe enodimenzionalno polje imen datotek v notaciji ScriptForge.FileSystem.FileNaming ali kot naslovi oken neshranjenih dokumentov.

### Skladnja:

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

### Primer:

V obeh spodnjih primerih lahko metoda vrne prazno polje, če ni odprt noben dokument.

##### V Basicu

          Dim docList As Variant
          docList = ui.Documents

##### V Pythonu

         docList = ui.Documents()

## GetDocument

Vrne instanco razreda Document ali enega njegovih podrazredov (Calc, Writer, Base, FormDocument), ki se sklicuje na dejavno okno, dano okno ali dejavni dokument.

### Skladnja:

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

svc.GetDocument(windowname: uno): svc

### Parametri:

windowname: glejte definicije zgoraj. Če ta argument ni podan, se uporabi dejavno okno. Predmeti UNO vrst com.sun.star.lang.XComponent in com.sun.star.comp.dba.ODatabaseDocument so tudi sprejeti. Zato podajanje ThisComponent ali ThisDatabaseDocument kot argumentov ustvari novo storitev SFDocuments.Document, Base ali Calc.

### Primer:

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

Če želite dostopati do trenutno dejavnega okna, uporabite lastnost ActiveWindow.

## Maximize

Poveča dejavno okno ali dano okno.

### Skladnja:

svc.Maximize(windowname: str)

### Parametri:

windowname: glejte zgornje definicije. Če argument ni podan, se trenutno dejavno okno poveča.

### Primer:

##### V Basicu

          ui.Maximize("Untitled 1")

##### V Pythonu

         ui.Maximize("Untitled 1")

## Minimize

Pomanjša dejavno okno ali dano okno.

### Skladnja:

svc.Minimize(windowname: str)

### Parametri:

windowname: glejte zgornje definicije. Če argument ni podan, se trenutno dejavno okno pomanjša.

### Primer:

##### V Basicu

         ui.Minimize()

##### V Pythonu

         ui.Minimize()

## OpenBaseDocument

Odpre obstoječi dokument programa LibreOffice Base. Metoda vrne predmet Base.

### Skladnja:

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

### Parametri:

filename: ime datoteke, ki jo želite odpreti. Slediti mora zapisu SF_FileSystem.FileNaming.

registrationname: ime za iskanje zbirke podatkov v registru zbirk podatkov. Prezrto, če je FileName <> "".

macroexecution: 0 = vedenje določa uporabniška prilagoditev, 1 = makrov ni možno izvajati, 2 = makre je možno izvajati. Privzeta vrednost je 0.

### Primer:

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

Za izboljšanje berljivosti kode lahko uporabite vnaprej določene konstante za argument macroexecution, kot je razvidno iz zgornjih primerov.

## OpenDocument (*)

Odpre obstoječi dokument LibreOffice z danimi možnostmi. Vrne predmet dokumenta ali enega njegovih podrazredov. Metoda vrne Nothing (v BASIC-u) / None (v Pythonu), če odpiranje ni uspelo, tudi če je vzrok odločitev uporabnika.

### Skladnja:

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

### Parametri:

filename: ime datoteke, ki jo želite odpreti. Slediti mora pravilom zapisa FileNaming storitve FileSystem.

password: geslo, potrebno za odpiranje, če je dokument zaščiten. Če je napačno ali ni prisotno, ko je dokument zaščiten, bo uporabnik povprašan za vnos gesla.

readonly: določa, ali je dokument namenjen samo branju, privzeto = False.

hidden: če je True, odpre nov dokument v ozadju (privzeto = False). Pozor pri uporabi: kasnejša aktivacija in zapiranje se lahko izvedeta samo programsko.

macroexecution: 0 = vedenje določa uporabniška prilagoditev, 1 = makrov ni možno izvajati, 2 = makre je možno izvajati. Privzeta vrednost je 0.

filtername: ime filtra, ki naj bo uporabljen za nalaganje dokumenta. Če ta argument podate, mora filter obstajati.

filteroptions: neobvezen niz možnosti, povezanih s filtrom.

### Primer:

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

Dejavnemu oknu spremeni velikost in/ali ga premakne. Odsotni in negativni argumenti so prezrti. Če je okno pomanjšano ali povečano, ga s klicem Resize brez argumentov obnovite.

### Skladnja:

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

### Parametri:

left, top: razdalje levega vrhnjega kota od levega in vrhnjega roba zaslona, v slikovnih točkah.

width, height: nove mere okna, v slikovnih točkah.

### Primer:

V naslednjih primerih se width in height okna se spremenita, top in left pa ostaneta nespremenjena.

##### V Basicu

          ui.Resize(Width := 500, Height := 500)

##### V Pythonu

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

Če želite spremeniti mere okna, ki ni dejavno, ga najprej aktivirajte z metodo Activate.

## RunCommand

Zažene ukaz UNO v trenutnem oknu. Nekaj tipičnih ukazov: Save (Shrani), SaveAs (Shrani kot), ExportToPDF (IzvoziVPDF), Undo (Razveljavi), Copy (Kopiraj), Paste (Prilepi) itn.

Ukazi se lahko zaženejo z ali brez argumentov. Argumenti se ne preverjajo pred izvajanjem ukaza. Če so ukaz ali njegovi argumenti neveljavni, se ne zgodi nič.

Celoten seznam ukazov UNO, ki jih lahko izvajate v LibreOffice, si oglejte na wiki-strani Development/DispatchCommands (v angl.).

### Skladnja:

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

### Parametri:

command: niz, ki vsebuje ime ukaza UNO. Vklučenost predpone ».uno:« ni obvezna. Sama pravilnost ukaza se ne preverja. Če se po klicu ukaza ne zgodi nič, je z ukazom oz. njegovim klicem najbrž nekaj narobe.

args: za vsak argument, ki bo posredovan ukazu, navedite par, ki vsebuje ime argumenta in njegovo vrednost.

### Primer:

##### V Basicu

Naslednji primer izvede ukaz .uno:About v trenutnem oknu.

        Set ui = CreateScriptService("UI")
        ui.RunCommand("About")

Spodaj je primer, ki izvede ukaz UNO .uno:BasicIDEAppear in poda potrebne argumente, da se odpre Basic IDE v določeni vrstici modula.

        ' Argumenti, posredovani ukazu:
        ' 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)

Upoštevajte, da klic ukaza BasicIDEAppear brez argumentov enostavno odpre Basic IDE.

##### 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 lahko pokličete tudi RunCommand z argumenti ključnih besed:

        ui.RunCommand(".uno:BasicIDEAppear", Document = "LibreOffice Macros & Dialogs", \
                      LibName = "ScriptForge", Name = "SF_Session", Line = 600)

Vsak program paketa LibreOffice ima na voljo lasten nabor ukazov. Enostaven način spoznavanja takšnih ukazov je priklic okna Orodja – Prilagodi – Tipkovnica. Ko postavite miško nad funkcijo na seznamu Funkcija, se pojavi namig z ustreznim ukazom UNO.

## SetStatusbar (*)

Prikaže besedilo in stolpec napredka v vrstici stanja dejavnega okna. Vsi naslednji klici iz istega izvajanja makra se nanašajo na isto vrstico stanja istega okna, tudi če okno ni več vidno. Klic brez argumentov ponastavi vrstico stanja v njeno navadno stanje.

### Skladnja:

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

### Parametri:

text: neobvezno besedilo, prikazano pred vrstico napredka.

percentage: neobvezna stopnja napredka med 0 in 100 (odstotek).

### Primer:

##### V Basicu

          Dim i As Integer
          For i = 0 To 100
              ui.SetStatusbar("Progress ...", i)
              Wait 50
          Next i
          ' Ponastavi vrstico stanja
          ui.SetStatusbar

##### V Pythonu

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

## ShowProgressBar

Prikaže glavno, nepodrejeno oz. ne-modalno okno. Določa njegov naslov, razlagalno besedilo in odstotek napredka, predstavljen v vrstici napredka. Pogovorno okno ostane vidno do klica metode brez argumenta ali do uporabnikovega ročnega zaprtja pogovornega okna.

### Skladnja:

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

### Parametri:

title: naslov, ki se pojavi na vrhu pogovornega okna. Privzeto = "ScriptForge".

text: neobvezno besedilo, prikazano nad vrstico napredka.

percentage: neobvezna stopnja napredka med 0 in 100 (odstotek).

### Primer:

##### V Basicu

          Dim i As Integer
          For i = 0 To 100
              ui.ShowProgressBar("Window Title", "Progress ..." & i & "/100", i)
              Wait 50
          Next i
          ' Zapre okno vrstice napredka
          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)
         # Zapre okno vrstice napredka
         ui.ShowProgressBar()

## WindowExists

Vrne True, če je dano okno mogoče identificirati.

### Skladnja:

svc.WindowExists(windowname: str): bool

### Parametri:

windowname: glejte zgornje definicije.

### Primer:

##### V Basicu

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

##### V Pythonu

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

Podobne teme

Storitev ScriptForge.Basic

Storitev SFDocuments.Calc

Storitev SFDocuments.Document