Service ScriptForge.UI

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

• Vensterselectie

• Vensters verplaatsen en vergroten/verkleinen

• Statusbalk-instellingen

• Weergave van een zwevende voortgangsbalk

• Maken van nieuwe vensters

• Toegang tot de onderliggende "documenten"

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:

• een volledig pad en bestandsnaam

• het laatste onderdeel van de volledige bestandsnaam of zelfs alleen het laatste onderdeel zonder het achtervoegsel

• de titel van het venster

• voor nieuwe documenten, zoiets als "Geen titel 1"

• een van de speciale vensters "BASICIDE" en "WELCOMESCREEN"

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.

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:

• 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

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

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

Eigenschappen

Constanten

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

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

svc.Activate(windowname: str): bool

windowname: Zie bovenstaande definities.

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

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

CreateBaseDocument

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

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

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.

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

Maak een nieuw Collabora Office-document van een bepaald type of op basis van een bepaald sjabloon. De methode retourneert een documentobject.

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

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.

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.

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

Retourneert een geopend documentobject dat verwijst naar het actieve venster, een bepaald venster of het actieve document.

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

svc.GetDocument(windowname: uno): svc

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.

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)

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.

svc.Maximize(windowname: str)

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

ui.Maximize("Untitled 1")

ui.Maximize("Untitled 1")

Minimize

Minimaliseert het actieve venster of het aangegeven venster.

svc.Minimize(windowname: str)

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

ui.Minimize()

ui.Minimize()

OpenBaseDocument

Open een bestaand Collabora Office-Base-document. De methode retourneert een documentobject.

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

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.

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)

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 Collabora Office-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.

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

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.

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.

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

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.

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

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.

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

ui.Resize(, ,500, 500)

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

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.

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

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

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.

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.

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)

Elke Collabora Office-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.

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

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

percentage: een optionele voortgangsgraad tussen 0 en 100.

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

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.

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

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.

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

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.

svc.WindowExists(windowname: str): bool

windowname: Zie bovenstaande definities.

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

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