ScriptForge.UI-tjenesten

Innhold

# ScriptForge.UI tjeneste

UI (User Interface)-tjenesten forenkler identifiseringen og manipuleringen av de forskjellige vinduene som utgjør hele LibreOffice-applikasjonen:

- Vindus-valg

- Flytting og endring av størrelse for vinduer

- Statuslinjeinnstillinger

- Visning av en flytende fremdriftslinje

- Oppretting av nye vinduer

- Tilgang til de underliggende "dokumentene"

UI-tjenesten er utgangspunktet for å åpne, opprette eller få tilgang til innholdet i nye eller eksisterende dokumenter fra et brukerskript.

## Definisjoner

### WindowName

Et vindu kan angitt ved hjelp av forskjellige måter:

- en fullstendig sti og filnavn

- den siste komponenten i det fullstendige filnavnet eller til og med bare den siste komponenten uten suffikset

- tittelen på vinduet

- for nye dokumenter, noe sånt som "Uten tittel 1"

- et av spesialvinduene "BASICIDE" og "VELKOMMEN"

Vindusnavnet skiller mellom store og små bokstaver.

### Dokument objekt

Metodene CreateDocument, CreateBaseDocument, GetDocument, OpenBaseDocument og OpenDocument, beskrevet nedenfor, generere dokumentobjekter. Når et vindu inneholder et dokument, representerer en forekomst av klassen Dokument det dokumentet. Et moteksempel Basic IDE er ikke et dokument, men er et vindu i vår terminologi. I tillegg har et dokument en type: Calc, Impress, Writer, ...

De spesifikke egenskapene og metodene som gjelder for dokumenter, implementeres i en dokumentklasse.

Implementeringen av dokumentobjektklassen gjøres i SFDocuments-tilknyttede bibliotek. Se «Dokument»-tjenesten.

## Tjenestepåkallelse

Før du bruker UI-tjenesten, må ScriptForge-biblioteket lastes eller importeres:

• Grunnleggende makroer krever å laste ScriptForge-biblioteket ved hjelp av følgende setning:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
• Python-skript krever import fra scriptforge-modulen:
fra scriptforge import CreateScriptService

##### I Basic

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

##### I Python

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

## Egenskaper

Navn | Skrivebeskyttet | Type | Beskrivelse
--- | --- | --- | ---
ActiveWindow | Ja | String | et gyldig og unikt WindowName for det aktive vinduet. Når vinduet ikke kan identifiseres, returneres en null-lengde streng.
Height | Ja | Integer | Returnerer høyden på det aktive vinduet i piksler.
Width | Ja | Integer | Returnerer bredden på det aktive vinduet i piksler.
X | Ja | Integer | Returnerer X-koordinaten til det aktive vinduet, som er avstanden til venstre kant av skjermen i piksler.
Y | Ja | Integer | Returnerer Y-koordinaten til det aktive vinduet, som er avstanden til øvre kant av skjermen i piksler. Denne verdien tar ikke hensyn til vindusdekorasjoner lagt til av operativsystemet ditt, så selv når vinduet er maksimert er kanskje ikke denne verdien null.

## Konstanter

Navn | Verdi | Beskrivelse
--- | --- | ---
MACROEXECALWAYS | 2 | Makroer kjøres alltid
MACROEXECNEVER | 1 | Makroer kjøres aldri
MACROEXECNORMAL | 0 | Makrokjøring avhenger av brukerinnstillingene

### Eksempel:

Eksemplene nedenfor viser en MsgBox med navnene på alle åpne dokumenter.

##### I Basic

         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

##### I Python

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

Liste over metoder i UI-tjenesten
Activate CreateBaseDocument CreateDocument (*) Documents GetDocument | Maximize Minimize OpenBaseDocument OpenDocument (*) Resize | RunCommand SetStatusBar (*) ShowProgressBar WindowExists

Merk, som et unntak, at metodene merket (*) ikke gjelder for Base dokumenter.

## Activate

Gjør det angitte vinduet aktivt. Metoden returnerer Sann hvis det gitte vinduet blir funnet og kan aktiveres. Det er ingen endring i det faktiske brukergrensesnittet hvis ingen vindu samsvarer med valget.

### Syntaks:

svc.Activate(windowname: str): bool

### Parametre:

vindusnavn: se definisjonene ovenfor.

### Eksempel:

##### I Basic

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

##### I Python

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

## CreateBaseDocument

Oppretter og lagrer et nytt LibreOffice Base-dokument som bygger inn en tom database av den gitte typen. Metoden returnerer en Dokument tjenesteforekomst.

### Syntaks:

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

### Parametre:

filnavn : Identifiserer filen som skal opprettes. Den må følge SF_FileSystem.FileNaming-notasjonen. Hvis filen allerede eksisterer, overskrives den uten forvarsel.

embeddeddatabase : Enten "HSQLDB" (standard), "FIREBIRD" eller "CALC".

registreringsnavn : Navnet som brukes til å lagre den nye databasen i databaseregisteret. Når = "" (standard), finner ingen registrering sted. Hvis navnet allerede eksisterer, overskrives det uten forvarsel.

calcfilename : Bare når embeddeddatabase = "CALC", representerer calcfilename filen som inneholder tabellene som Calc-ark. Filen må eksistere, ellers oppstår det en feil.

### Eksempel:

##### I Basic

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

##### I Python

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

Opprett et nytt LibreOffice-dokument av en gitt type eller basert på en gitt mal. Metoden returnerer en forekomst av dokumentklassen eller en av dens underklasser (Calc, Writer).

### Syntaks:

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

### Parametre:

documenttype : "Calc", "Writer", etc. Hvis fraværende, må templatefile argumentet være tilstede.

malfil : Hele Filnavn til malen som det nye dokumentet skal bygges på. Hvis filen ikke eksisterer, ignoreres argumentet. Tjenesten FileSystem gir egenskapene TemplatesFolder og UserTemplatesFolder for å hjelpe til med å bygge argumentet.

skjult: hvis True, åpne det nye dokumentet i bakgrunnen (standard = False). For å bruke med forsiktighet: aktivering eller stenging etterpå kan bare skje programmatisk.

### Eksempel:

I begge eksemplene nedenfor oppretter det første kallet til CreateDocument-metoden et tomt Calc-dokument, mens det andre oppretter et dokument fra en malfil.

##### I Basic

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

##### I Python

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

## Documents

Listen over åpne dokumenter. Spesielle vinduer ignoreres. Denne listen består av en nullbasert endimensjonal matrise enten av filnavn - med ScriptForge.FileSystem.FileName-notasjon - eller vindu titler for ulagrede dokumenter.

### Syntaks:

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

### Eksempel:

I begge eksemplene nedenfor kan metoden returnere en tom matrise hvis det ikke er noen åpne dokumenter.

##### I Basic

          Dim docList As Variant
          docList = ui.Documents

##### I Python

         docList = ui.Documents()

## GetDocument

Returnerer en forekomst av Document-klassen eller en av dens underklasser (Calc, Writer, Base, FormDocument) som refererer til enten et gitt vindu eller det aktive dokumentet.

### Syntaks:

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

svc.GetDocument(windowname: uno): svc

### Parametre:

vindusnavn: Se definisjonene over. Hvis dette argumentet er fraværende, brukes det aktive vinduet. UNO-objekter av typene com.sun.star.lang.XComponent eller com.sun.star.comp.dba.ODatabaseDocument godtas også. Ved å sende ThisComponent eller ThisDatabaseDocument som argument opprettes et nytt SFDocuments. Dokument, Base eller Calc-tjeneste.

### Eksempel:

##### I Basic

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

##### I Python

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

For å få tilgang til navnet på det aktive vinduet, se egenskapen ActiveWindow.

## Maximize

Maksimerer det aktive vinduet eller det gitte vinduet.

### Syntaks:

svc.Maximize(windowname: str)

### Parametre:

vindusnavn: se definisjonene over. Hvis dette argumentet er fraværende, maksimeres det aktive vinduet.

### Eksempel:

##### I Basic

          ui.Maximize("Untitled 1")

##### I Python

         ui.Maximize("Untitled 1")

## Minimize

Minimerer det aktive vinduet eller det gitte vinduet.

### Syntaks:

svc.Minimize(windowname: str)

### Parametre:

vindusnavn: se definisjonene over. Hvis dette argumentet er fraværende, minimeres det aktive vinduet.

### Eksempel:

##### I Basic

         ui.Minimize()

##### I Python

         ui.Minimize()

## OpenBaseDocument

Åpne et eksisterende LibreOffice Base-dokument. Metoden returnerer et Base-objekt.

### Syntaks:

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

### Parametre:

filnavn: Identifiserer filen som skal åpnes. Den må følge SF_FileSystem.FileNaming-notasjonen.

registreringsnavn: Navnet som skal brukes for å finne databasen i databaseregisteret. Det ignoreres hvis Filnavn <> "".

makrokjøring: 0 = adferd er definert av brukerkonfigurasjonen, 1 = makroer er ikke kjørbare, 2 = makroer er kjørbare. Standard er 0.

### Eksempel:

##### I Basic

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

##### I Python

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

For å forbedre kodelesbarheten kan du bruke forhåndsdefinerte konstanter for makrokjøring-argumentet, som i eksemplene ovenfor .

## OpenDocument (*)

Åpner et eksisterende LibreOffice-dokument med de angitte alternativene. Returnerer et dokumentobjekt eller en av dets underklasser. Metoden returnerer Ingenting (i BASIC) eller Ingen (i Python) hvis åpningen mislyktes, selv når feilen er forårsaket av en brukerbeslutning.

### Syntaks:

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

### Parametre:

filnavn: Identifiserer filen som skal åpnes. Den må følge FileName-notasjonen til FileSystem-tjenesten.

passord: Brukes når dokumentet er beskyttet. Hvis det er feil eller fraværende mens dokumentet er beskyttet, vil brukeren bli bedt om å angi et passord.

skrivebeskyttet: Standard = Usann.

skjult: hvis Sann, åpne det nye dokumentet i bakgrunnen (standard = Usann). For å bruke med forsiktighet: aktivering eller stenging etterpå kan bare skje programmatisk.

makrokjøring: 0 = atferd er definert av brukerkonfigurasjonen, 1 = makroer er ikke kjørbare, 2 = makroer er kjørbare. Standard er 0.

filternavn: Navnet på et filter som skal brukes for å laste dokumentet. Hvis det finnes, må filteret eksistere.

filteralternativer: En valgfri streng med alternativer knyttet til filteret.

### Eksempel:

##### I Basic

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

##### I Python

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

## Resize

Endre størrelse og/eller flytte det aktive vinduet. Fraværende og negative argumenter ignoreres. Hvis vinduet er minimert eller maksimert, gjenopprettes det ved å ringe Endre størrelse uten argumenter.

### Syntaks:

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

### Parametre:

venstre, øverst: Avstander fra øverste venstre hjørne fra øvre og venstre kant av skjermen, i piksler.

bredde, høyde: Nye dimensjoner for vinduet, i piksler.

### Eksempel:

I de følgende eksemplene endres bredden og høyden av vinduet mens top og venstre forblir uendret.

##### I Basic

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

##### I Python

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

For å endre størrelse på et vindu som ikke er aktivt, aktiverer du det først ved å bruke Aktiver-metoden.

## RunCommand

Kjører en UNO-kommando i det gjeldende vinduet. Noen typiske kommandoer er: Save, SaveAs, ExportToPDF, Undo, Copy, Paste, etc.

Kommandoer kan kjøres med eller uten argumenter. Argumenter blir ikke validert før kommandoen kjøres. Hvis kommandoen eller dens argumenter er ugyldige, vil ingenting skje.

For en fullstendig liste over UNO-kommandoer som kan kjøres i LibreOffice, se Wiki-siden Development/DispatchCommands.

### Syntaks:

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

### Parametre:

kommando: Skrevet av store og små bokstaver som inneholder UNO-kommandonavnet. Inkludering av prefikset ".uno:" i kommandoen er valgfritt. Selve kommandoen kontrolleres ikke for korrekthet. Hvis ingenting skjer etter kommandoanropet, er kommandoen sannsynligvis feil.

args: For hvert argument som skal sendes til kommandoen, spesifiser et par som inneholder argumentnavnet og verdien.

### Eksempel:

##### I Basic

Følgende eksempel kjører kommandoen .uno:About i det gjeldende vinduet.

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

Nedenfor er et eksempel som kjører UNO-kommandoen .uno:BasicIDEAppear og sender argumentene som kreves for å åpne Basic IDE på en bestemt linje i en modul.

        ' Argumenter sendt til kommandoen:
        ' 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)

Merk at å kalle kommandoen BasicIDEAppear uten argumenter vil ganske enkelt åpne Basic IDE.

##### I Python

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

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

I Python er det også mulig å kalle RunCommand ved å bruke søkeordargumenter:

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

Hver LibreOffice-komponent har sitt eget sett med kommandoer tilgjengelig. En enkel måte å lære kommandoer på er å gå til Verktøy - Tilpass - Tastatur. Når du plasserer musen over en funksjon i Funksjon-listen, vises et verktøytips med den tilsvarende UNO-kommandoen.

## SetStatusbar (*)

Vis en tekst og en fremdriftslinje i statuslinjen i det aktive vinduet. Alle påfølgende anrop i samme makrokjøring refererer til den samme statuslinjen i det samme vinduet, selv om vinduet ikke er synlig lenger. Et anrop uten argumenter tilbakestiller statuslinjen til normal tilstand.

### Syntaks:

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

### Parametre:

tekst: En valgfri tekst som skal vises foran fremdriftslinjen.

prosent: en valgfri grad av fremgang mellom 0 og 100.

### Eksempel:

##### I Basic

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

##### I Python

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

## ShowProgressBar

Viser en ikke-modal dialogboks. Spesifiser tittelen, en forklarende tekst og en prosentandel av fremdriften som skal representeres på en fremdriftslinje. Dialogen vil forbli synlig inntil et kall til metoden uten argumenter eller til brukeren lukker dialogen manuelt.

### Syntaks:

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

### Parametre:

tittel : Tittelen som vises øverst i dialogboksen. Standard = "ScriptForge".

tekst: En valgfri tekst som skal vises over fremdriftslinjen.

prosent: en valgfri grad av fremgang mellom 0 og 100.

### Eksempel:

##### I Basic

          Dim i As Integer
          For i = 0 To 100
              ui.ShowProgressBar("Window Title", "Progress ..." & i & "/100", i)
              Wait 50
          Next i
          ' Lukker fremdriftslinjevinduet
          ui.ShowProgressBar

##### I Python

         from time import sleep
         for i in range(101):
             ui.ShowProgressBar("Window Title", "Progress ... " + str(i) + "/100", i)
             sleep(0.05)
         # Lukker fremdriftslinjevinduet
         ui.ShowProgressBar()

## WindowExists

Returnerer Sann hvis det gitte vinduet kunne identifiseres.

### Syntaks:

svc.WindowExists(windowname: str): bool

### Parametre:

vindusnavn: se definisjonene ovenfor.

### Eksempel:

##### I Basic

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

##### I Python

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

Lignende emner

ScriptForge.Grunnleggende tjeneste

SFDocuments.Calc tjeneste

SFDocuments.Dokument tjeneste