ScriptForge.UI tjeneste

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

tip

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:

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.

tip

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:

note

• 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


warning

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

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

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

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.

tip

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

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

Supporter oss!