Inhoud
Index 🔎︎

# 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 methoden CreateDocument, CreateBaseDocument, GetDocument en OpenDocument, hieronder beschreven, 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

##### 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.
Documents | Ja | String array | De lijst met de momenteel geopende documenten. Speciale vensters worden genegeerd. Deze lijst bestaat uit een op nul gebaseerde eendimensionale matrix van bestandsnamen (in SF_FileSystem.FileNaming-notatie) of venstertitels voor niet-opgeslagen documenten.

## 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 (*) GetDocument | Maximize Minimize OpenBaseDocument OpenDocument (*) | Resize SetStatusBar (*) ShowProgressBar WindowExists

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 op basis van een bepaald sjabloon. De methode retourneert een documentobject.

### 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")
         FSO = CreateScriptService("FileSystem")
         myDoc2 = ui.CreateDocument(templatefile = FSO.BuildPath(FSO.TemplatesFolder, "personal/CV.ott"))

## GetDocument

Retourneert een documentobject dat verwijst naar het actieve venster, een bepaald venster of 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

         myDoc = ui.GetDocument(r"C:\Documents\My file.odt")
         from scriptforge import CreateScriptService
         bridge = CreateScriptService("Basic")
         myDoc = ui.GetDocument(bridge.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-Base-document. De methode retourneert een documentobject.

### 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 hebben. Als het bestand al bestaat, wordt het zonder waarschuwing overschreven

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.

### Voorbeeld:

##### In BASIC

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

##### In Python

         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) / None (in Python) als de opening is mislukt, zelfs als de fout wordt veroorzaakt door een gebruikersbeslissing.

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

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

         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(, ,500, 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.

## 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: str = -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