Inhoud

# Service ScriptForge.UI

De service UI (User Interface) vereenvoudigt de identificatie en de manipulatie van de verschillende vensters die de hele LibreOffice-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 methodes 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 methodes 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

##### 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 methodes in de UI-service
Activate CreateBaseDocument CreateDocument (*) Documents GetDocument | Maximize Minimize OpenBaseDocument OpenDocument (*) Resize | RunCommand SetStatusBar (*) ShowProgressBar WindowExists

Merk op dat bij uitzondering de methodes 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)

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)

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)

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

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

Verwante onderwerpen

ScriptForge.Basic service

SFDocuments.Calc service

SFDocuments.Document-service