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

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

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

Egenskaper

Konstanter

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

      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)
   

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.

svc.Activate(windowname: str): bool

vindusnavn: se definisjonene ovenfor.

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

      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.

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

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.

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

Opprett et nytt LibreOffice-dokument av en gitt type eller basert på en gitt mal. Metoden returnerer et dokumentobjekt.

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

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.

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.

      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

Returnerer et åpent dokumentobjekt som refererer til enten det aktive vinduet, et gitt vindu eller det aktive dokumentet.

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

svc.GetDocument(windowname: uno): svc

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.

      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)
   

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

Maximize

Maksimerer det aktive vinduet eller det gitte vinduet.

svc.Maximize(windowname: str)

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

      ui.Maximize("Untitled 1")
   

     ui.Maximize("Untitled 1")
   

Minimize

Minimerer det aktive vinduet eller det gitte vinduet.

svc.Minimize(windowname: str)

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

     ui.Minimize()
   

     ui.Minimize()
   

OpenBaseDocument

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

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

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 = atferd er definert av brukerkonfigurasjonen, 1 = makroer er ikke kjørbare, 2 = makroer er kjørbare.

      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)
   

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.

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

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.

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.

      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

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.

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

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.

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

      ui.Resize(, ,500, 500)
   

     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.

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

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.

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.

    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.

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

tekst: En valgfri tekst som skal vises foran fremdriftslinjen.

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

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

     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.

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

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.

      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
   

     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.

svc.WindowExists(windowname: str): bool

vindusnavn: se definisjonene ovenfor.

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

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