Service ScriptForge.UI

De service UI (User Interface) vereenvoudigt de identificatie en de manipulatie van de verschillende vensters die de hele LibreOffice-toepassing vormen:

tip

De service UI is het startpunt voor het openen, creƫren of benaderen van de inhoud van nieuwe of bestaande documenten vanuit een gebruikersscript.


Definities

WindowName

Een venster kan op verschillende manieren worden aangewezen:

De naam van het venster is hoofdlettergevoelig.

Object 'Document'

De hieronder beschreven methoden CreateDocument, CreateBaseDocument, GetDocument, OpenBaseDocument en OpenDocument, genereren documentobjecten. Als een venster een document bevat, vertegenwoordigt een instantie van de klasse Document dat document. Een tegenvoorbeeld de Basic IDE is geen document maar een venster in onze terminologie. Daarnaast heeft een document een type: Calc, Impress, Writer, ...

De specifieke eigenschappen en methoden die van toepassing zijn op documenten zijn geĆÆmplementeerd in een documentklasse.

tip

De implementatie van de documentobjectenklasse wordt gedaan in de SFDocuments geassocieerde bibliotheek. Zie de service "Document".


Service aanroep

Voordat de service UI gebruikt kan worden, moet de bibliotheek ScriptForge eerst worden geladen of geĆÆmporteerd:

note

ā€¢ Basic macro's kunnen de bibliotheek ScriptForge laden met de instructie:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

ā€¢ Python scripts kunnen de module scriptforge importeren met:
from scriptforge import CreateScriptService


In BASIC

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

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

Eigenschappen

Name

AlleenLezen

Type

Beschrijving

ActiveWindow

Ja

String

een geldige en unieke WindowName voor het huidige actieve venster. Wanneer het venster niet kan worden geĆÆdentificeerd, wordt een tekenreeks met lengte nul geretourneerd.

Height

Ja

Integer

Retourneert de hoogte van het actieve venster in pixels.

Width

Ja

Integer

Retourneert de breedte van het actieve venster in pixels.

X

Ja

Integer

Retourneert de X-coƶrdinaat van het actieve venster, de afstand tot de linkerrand van het scherm in pixels.

Y

Ja

Integer

Retourneert de Y-coƶrdinaat van het actieve venster, de afstand tot de bovenrand van het scherm in pixels. Deze waarde houdt geen rekening met vensterdecoraties die door uw besturingssysteem zijn toegevoegd, dus zelfs wanneer het venster is gemaximaliseerd, kan deze waarde niet nul zijn.


Constanten

Name

Waarde

Beschrijving

MACROEXECALWAYS

2

Macro's worden altijd uitgevoerd

MACROEXECNEVER

1

Macro's worden nooit uitgevoerd

MACROEXECNORMAL

0

Macro-uitvoering is afhankelijk van gebruikersinstellingen


Voorbeeld:

De onderstaande voorbeelden tonen een MsgBox met de namen van alle momenteel geopende documenten.

In 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
   
In Python

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

Lijst met methoden in de UI-service

Activate
CreateBaseDocument
CreateDocument (*)
Documents
GetDocument

Maximize
Minimize
OpenBaseDocument
OpenDocument (*)
Resize

RunCommand
SetStatusBar (*)
ShowProgressBar
WindowExists


warning

Merk op dat bij uitzondering de methoden gemarkeerd met (*) niet van toepassing zijn op Base-documenten.


Activate

Maak het aangegeven venster actief. De methode retourneert True als het aangegeven venster is gevonden en kan worden geactiveerd. Er is geen verandering in de eigenlijke gebruikersinterface als er geen venster overeenkomt met de selectie.

Syntaxis:

svc.Activate(windowname: str): bool

Parameters:

windowname: Zie bovenstaande definities.

Voorbeeld:

In BASIC

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

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

CreateBaseDocument

Creƫert en bewaart een nieuw LibreOffice-Base-document dat een lege database van het opgegeven type insluit. De methode retourneert een service-instantie Document.

Syntaxis:

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

Parameters:

filename: Identificeert het bestand dat moet worden gemaakt. Het moet de notatie SF_FileSystem.FileNaming volgen. Als het bestand al bestaat, wordt het zonder waarschuwing overschreven.

embeddeddatabase : "HSQLDB" (standaard), "FIREBIRD" of "CALC".

registrationname : De naam die wordt gebruikt om de nieuwe database op te slaan in het databaseregister. When = "" (standaard), er vindt geen registratie plaats. Als de naam al bestaat, wordt deze zonder waarschuwing overschreven.

calcfilename : Alleen wanneer embeddeddatabase = "CALC", vertegenwoordigt calcfilename het bestand dat de tabellen bevat als Calc-bladen. Het bestand moet bestaan, anders treedt er een fout op.

Voorbeeld:

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

Maak een nieuw LibreOffice-document van een bepaald type of gebaseerd op een bepaalde sjabloon. De methode retourneert een exemplaar van de documentklasse of een van zijn subklassen (Calc, Writer).

Syntaxis:

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

Parameters:

documenttype : "Calc", "Writer", enz. Indien afwezig, moet het argument templatefile aanwezig zijn.

templatefile : De volledige FileName van de sjabloon om het nieuwe document op te bouwen. Als het bestand niet bestaat, wordt het argument genegeerd. De service FileSystem biedt de eigenschappen TemplatesFolder en UserTemplatesFolder om het argument op te bouwen.

hidden: indien True, open het nieuwe document op de achtergrond (standaard = False). Om met voorzichtigheid te gebruiken: activering of sluiting achteraf kan alleen programmatisch gebeuren.

Voorbeeld:

In beide onderstaande voorbeelden creƫert de eerste aanroep van de methode CreateDocument een leeg Calc-document, terwijl de tweede een document maakt vanuit een sjabloonbestand.

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

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

Documents

De lijst met de momenteel geopende documenten. Speciale vensters worden genegeerd. Deze lijst bestaat uit een op nul gebaseerde eendimensionale array van bestandsnamen - met de notatie ScriptForge.FileSystem.FileNameming - of van venster titels voor niet-opgeslagen documenten.

Syntaxis:

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

Voorbeeld:

In beide onderstaande voorbeelden kan de methode een lege matrix retourneren als er geen documenten geopend zijn.

In BASIC

      Dim docList As Variant
      docList = ui.Documents
   
In Python

     docList = ui.Documents()
   

GetDocument

Retourneert een exemplaar van de klasse Document of een van zijn subklassen (Calc, Writer, Base, FormDocument) die verwijst naar een bepaald venster of naar het actieve document.

Syntaxis:

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

svc.GetDocument(windowname: uno): svc

Parameters:

windowname: Zie de definities hierboven. Als dit argument ontbreekt, wordt het actieve venster gebruikt. UNO-objecten van het type com.sun.star.lang.XComponent of com.sun.star.comp.dba.ODatabaseDocument worden ook geaccepteerd. Door ThisComponent of ThisDatabaseDocument als argument door te geven, ontstaat er een nieuwe service SFDocuments. Document, Base of Calc.

Voorbeeld:

In BASIC

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

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

Raadpleeg de eigenschap ActiveWindow om toegang te krijgen tot de naam van het huidige actieve venster.


Maximize

Maximaliseert het actieve venster of het gegeven venster.

Syntaxis:

svc.Maximize(windowname: str)

Parameters:

windowname: zie de definities hierboven. Als dit argument ontbreekt, wordt het actieve venster gemaximaliseerd.

Voorbeeld:

In BASIC

      ui.Maximize("Untitled 1")
   
In Python

     ui.Maximize("Untitled 1")
   

Minimize

Minimaliseert het actieve venster of het aangegeven venster.

Syntaxis:

svc.Minimize(windowname: str)

Parameters:

windowname: zie de definities hierboven. Als dit argument ontbreekt, wordt het actieve venster geminimaliseerd.

Voorbeeld:

In BASIC

     ui.Minimize()
   
In Python

     ui.Minimize()
   

OpenBaseDocument

Open een bestaand LibreOffice-basisdocument. De methode retourneert een Base-object.

Syntaxis:

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

Parameters:

filename: Identificeert het te openen bestand. Het moet de notatie SF_FileSystem.FileNaming volgen.

registrationname: De naam die moet worden gebruikt om de database in het databaseregister te vinden. Het wordt genegeerd als FileName <> "".

macroexecution: 0 = gedrag wordt bepaald door de gebruikersconfiguratie, 1 = macro's zijn niet uitvoerbaar, 2 = macro's zijn uitvoerbaar. Standaard is 0.

Voorbeeld:

In BASIC

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

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

Om de leesbaarheid van de code te verbeteren, kunt u vooraf gedefinieerde constanten gebruiken voor het argument macroexecution, zoals in de bovenstaande voorbeelden.


OpenDocument (*)

Opent een bestaand LibreOffice-document met de gegeven opties. Retourneert een documentobject of een van zijn subklassen. De methode retourneert Nothing (in BASIC) of None (in Python) als de opening is mislukt, zelfs als de fout wordt veroorzaakt door een beslissing van de gebruiker.

Syntaxis:

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

Parameters:

filename: Identificeert het te openen bestand. Het moet de notatie FileNaming volgen van de service FileSystem.

password: Te gebruiken wanneer het document is beveiligd. Als het onjuist of afwezig is terwijl het document is beveiligd, wordt de gebruiker gevraagd een wachtwoord in te voeren.

readonly: Standaard = False.

hidden: indien True, opent het nieuwe document op de achtergrond (standaard = False). Om met voorzichtigheid te gebruiken: activering of sluiting achteraf kan alleen programmatisch gebeuren.

macroexecution: 0 =gedrag wordt bepaald door de gebruikersconfiguratie, 1 = macro's zijn niet uitvoerbaar, 2 = macro's zijn uitvoerbaar. Standaard is 0.

filtername: De naam van een filter dat moet worden gebruikt voor het laden van het document. Indien aanwezig, moet het filter aanwezig zijn.

filteroptions: Een optionele tekenreeks met opties die aan het filter zijn gekoppeld.

Voorbeeld:

In BASIC

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

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

Resize

Verkleint en/of verplaatst het actieve venster. Afwezige en negatieve argumenten worden genegeerd. Als het venster geminimaliseerd of gemaximaliseerd is, zal het aanroepen van Resize het zonder argumenten herstellen.

Syntaxis:

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

Parameters:

left, top: Afstanden van de linkerbovenhoek tot de boven- en linkerrand van het scherm, in pixels.

width, height: Nieuwe afmetingen van het venster, in pixels.

Voorbeeld:

In de volgende voorbeelden worden de breedte en hoogte van het venster gewijzigd terwijl top en links ongewijzigd blijven.

In BASIC

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

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

Om de grootte van een inactief venster te wijzigen, activeert u het eerst met de methode Activate.


RunCommand

Voert een UNO-opdracht uit op het huidige venster. Een paar typische opdrachten zijn: Save, SaveAs, ExportToPDF, Undo, Copy, Paste, etc.

Opdrachten kunnen met of zonder argumenten worden uitgevoerd. Argumenten worden niet gevalideerd voordat de opdracht wordt uitgevoerd. Als de opdracht of zijn argumenten ongeldig zijn, gebeurt er niets.

tip

Voor een volledige lijst van UNO-commando's die in LibreOffice kunnen worden uitgevoerd, raadpleegt u de Wiki-pagina Development/DispatchCommands.


Syntaxis:

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

Parameters:

command: Hoofdlettergevoelige tekenreeks die de UNO-opdrachtnaam bevat. Het opnemen van het voorvoegsel ".uno:" in de opdracht is optioneel. De opdracht zelf wordt niet op juistheid gecontroleerd. Als er niets gebeurt na de opdrachtaanroep, is de opdracht waarschijnlijk verkeerd.

args: Geef voor elk argument dat aan de opdracht moet worden doorgegeven een paar op dat de naam en waarde van het argument bevat.

Voorbeeld:

In BASIC

In het volgende voorbeeld wordt de opdracht .uno:About uitgevoerd in het huidige venster.


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

Hieronder ziet u een voorbeeld dat de UNO-opdracht .uno:BasicIDEAppear uitvoert en de argumenten doorgeeft die nodig zijn om de Basic-IDE op een specifieke regel van een module te openen.


    ' Aan de opdracht doorgegeven argumenten:
    ' 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 op dat het aanroepen van de opdracht BasicIDEAppear zonder argumenten gewoon de Basic-IDE zal openen.

In Python

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

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

In Python is het ook mogelijk om RunCommand aan te roepen met trefwoordargumenten:


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

Elke LibreOffice-component heeft zijn eigen set opdrachten beschikbaar. Een gemakkelijke manier om opdrachten te leren is door naar Extra - Aanpassen - Toetsenbord te gaan. Wanneer u uw muisaanwijzer over een functie in de lijst Functie plaatst, verschijnt er een helptip met de bijbehorende UNO-opdracht.


SetStatusbar (*)

Geef een tekst en een voortgangsbalk weer in de statusbalk van het actieve venster. Alle volgende oproepen in dezelfde macro-run verwijzen naar dezelfde statusbalk van hetzelfde venster, zelfs als het venster niet meer zichtbaar is. Een aanroep zonder argumenten zet de statusbalk terug naar de normale status.

Syntaxis:

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

Parameters:

text: Een optionele tekst die vĆ³Ć³r de voortgangsbalk moet worden weergegeven.

percentage: een optionele voortgangsgraad tussen 0 en 100.

Voorbeeld:

In BASIC

      Dim i As Integer
      For i = 0 To 100
          ui.SetStatusbar("Progress ...", i)
          Wait 50
      Next i
      ' Herstelt de statusbalk
      ui.SetStatusbar
   
In Python

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

ShowProgressBar

Geeft een niet-modaal dialoogvenster weer. Geef de titel, een verklarende tekst en een voortgangspercentage op dat op een voortgangsbalk moet worden weergegeven. Het dialoogvenster blijft zichtbaar totdat de methode zonder argumenten wordt aangeroepen of totdat de gebruiker het dialoogvenster handmatig sluit.

Syntaxis:

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

Parameters:

title : De titel die bovenaan het dialoogvenster verschijnt. Standaard = "ScriptForge".

text: Een optionele tekst die boven de voortgangsbalk moet worden weergegeven.

percentage: een optionele voortgangsgraad tussen 0 en 100.

Voorbeeld:

In BASIC

      Dim i As Integer
      For i = 0 To 100
          ui.ShowProgressBar("Window Title", "Progress ..." & i & "/100", i)
          Wait 50
      Next i
      ' Sluit het venster met de voortgangsbalk
      ui.ShowProgressBar
   
In Python

     from time import sleep
     for i in range(101):
         ui.ShowProgressBar("Window Title", "Progress ... " + str(i) + "/100", i)
         sleep(0.05)
     # Sluit het venster met de voortgangsbalk
     ui.ShowProgressBar()
   

WindowExists

Retourneert True als het opgegeven venster kon worden geĆÆdentificeerd.

Syntaxis:

svc.WindowExists(windowname: str): bool

Parameters:

windowname: Zie bovenstaande definities.

Voorbeeld:

In BASIC

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

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

Help ons, alstublieft!