Innhald

# Tenesta ScriptForge.UI

T Tenesta UI (User Interface = brukargrensesnitt) gjer identifikasjonen og handsaminga av dei ulike vindauga som heile LibreOffice-programmet er bygd opp av.

- Windows selection

- Flytting og endring av storleiken på vindauga

- Innstillingar for statuslinja

- Å visa ei flytande framdriftslinje

- Laga nye vindauge

- Tilgang til dei underliggjande «dokumenta»

UI-tenesta er utgangspunktet for å opna, laga eller få tilgang til innhaldet i nye eller dokument som finst få før i eit brukarskript.

## Definisjonar

### WindowName

Eit vindauge kan beskrivast på mange ulike måtar:

- ein full sti med filnamn

- den siste komponenten i det fulle filnamnet, eller endatil den siste komponenten utan filetternamnet

- tittelen på vindauget

- for nye dokument, noko som liknar på «Utan tittel 1»

- eit av spesialvindauga «BASICIDE» og «WELCOMESCREEN»

Namnet på vindauget skil mellom store og små bokstavar.

### Document-objektet

Metodane CreateDocument, CreateBaseDocument, GetDocument, OpenBaseDocument og OpenDocument omtalte nedanfor genererer dokumentobjekt. Når eit vindauge inneheld eit dokument, representerer ein førekomst av klassen Document det dokumentet. Eit moteksempel er at Basic IDE ikkje er eit dokument, men er et vindauge i vår terminologi. I tillegg har eit dokument ein type: Calc, Impress, Writer, …

Dei spesifikke eigenskapane og metodane som kan brukast på dokument er implementerte i ein dokument-klasse.

Implementeringa av dokument-objektklassen vert gjort i det tilknytte biblioteket SFDocuments. Sjå tenesta for dette i "Document".

## Oppkall av tenester

Før du brukar tenesta UI, må biblioteket ScriptForge vera lasta inn eller importert:

• Grunnleggjande makroar krev innlasting av biblioteket ScriptForge ved hjelp av denne setninga:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
• Python-skript krev import frå scriptforge-modulen:
from scriptforge import CreateScriptService

##### I Basic

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

##### I Python

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

## Eigenskapar

Namn | Skriveverna | Type | Beskriving
--- | --- | --- | ---
ActiveWindow | Ja | String | eit gyldig og unikt WindowName til det gjeldande aktive vindauget. Når vindauget ikkje kan identifiserast, vert det returnert ein streng med null lengd.
Height | Ja | Integer | Returnerer høgda i det aktive vindauget i pikslar.
Width | Ja | Integer | Returnerer breidda i det aktive vindauget i pikslar.
X | Ja | Integer | Returnerer X-koordinaten til det aktive vindauget, som er avstanden til venstre kant av skjermen i pikslar.
Y | Ja | Integer | Returnerer Y-koordinaten til det aktive vindauget. Dette er avstanden til øvre kant av skjermen i pikslar. Denne verdien tar ikkje omsyn til vindaugedekorasjonar lagt til av operativsystemet, så sjølv når vindauget er maksimert, er kanskje denne verdien ikkje null.

## Konstantar

Namn | Verdi | Beskriving
--- | --- | ---
MACROEXECALWAYS | 2 | Makroar vert alltid utført
MACROEXECNEVER | 1 | Makroar vert aldri utført
MACROEXECNORMAL | 0 | Køyringa av makroar er avhengig av brukarinnstillingane

### Eksempel:

Eksempelet nedanfor viser ein MsgBox med namna på alle gjeldande opne dokument.

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

##### I Python

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

Liste over metodar i tenesta UI
Activate CreateBaseDocument CreateDocument (*) Documents GetDocument | Maximize Minimize OpenBaseDocument OpenDocument (*) Resize | RunCommand SetStatusBar (*) ShowProgressBar WindowExists

Merk, som eit unntak, at metodane merkt med (*) ikkje kan brukast i Basedokument.

## Activate

Gjer det gjevne vindauget aktivt. Metoden returnerer Sann viss det gjevne vindauget vert funne og kan aktiverast. Det er ingen endring i det gjeldande brukargrensesnittet viss ingen vindauge samsvarar med valet.

### Syntaks:

svc.Activate(windowname: str): bool

### Parametrar:

windowname: sjå definisjonane ovanfor.

### Eksempel:

##### I Basic

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

##### I Python

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

## CreateBaseDocument

Opprettar og lagrar eit nytt LibreOffice Base-dokument som byggjar inn ein tom database av den gjevne typen. Metoden returnerer ein førekomst av tenesta Document.

### Syntaks:

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

### Parametrar:

filname: Identifiserer fila som skal opprettast. Det må følgja SF_FileSystem.FileNaming-notasjonen. Viss fila finst frå før, vert ho overskrive utan varsel.

embeddeddatabase: Anten «HSQLDB» (standard), «FIREBIRD» eller «CALC».

registrationname : Namnet som vert brukt til å lagra den nye databasen i databaseregisteret. Når = "" (standard), vert ingenting registrert. Viss namnet er i bruk frå før, vert det overskrive utan varsel.

calcfilename: Berre når embeddeddatabase = "CALC", representerer calcfilename fila som inneheld tabellane som Calc-ark. Fila må finnast frå før, elles vert det generert det ein feil.

### Eksempel:

##### I 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")

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

Oppretter eit nytt LibreOffice-dokument av ein gjeven type, eller basert på ein gjeven mal. Metoden returnerer ein førekomst av dokumentetklassen eller ein av underklassane (Calc, Writer).

### Syntaks:

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

### Parametrar:

documenttype : «Calc», «Writer»,osv. Viss denne manglar, må argumentet templatefile vera til stades.

templatefile: Det fullstendige FileName på malen som det nye dokumentet skal byggjast på. Viss fila ikkje finst, vert det sett bort frå argumentet. Tenesta FileSystem inneheld eigenskapane TemplatesFolder og UserTemplatesFolder som hjelper til med å byggja argumentet.

hidden: viss Sann, opnar du det nye dokumentet i bakgrunnen (standard = Usann). Må brukast med varsemd sidan å aktivering eller lukking seinare berre kan skje programmatisk.

### Eksempel:

I begge eksempla nedanfor set det første kallet til metoden CreateDocument opp eit tomt Calc-dokument, medan det andre set opp eit dokument frå ei malfil.

##### I 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"))

##### I Python

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

## Documents

Lista over opne dokument. Spesialvindauge vert ignorerte. Denne lista inneheld ei null-basert eindimensjonal matrise anten av filnamn ‒ ved bruk av ScriptForge.Filsystem.FileNaming-notasjon ‒ eller vindaugetitler for dokument som ikkje er lagra.

### Syntaks:

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

### Eksempel:

I begge eksempla nedeanfor kan metoden returnera ei tom matrise viss det ikkje er nokre opne dokument.

##### I Basic

          Dim docList As Variant
          docList = ui.Documents

##### I Python

         docList = ui.Documents()

## GetDocument

Returnerer ein førekomst av dokumentklassen eller ein av underklassane (Calc, Writer, Base,Skjemadokument) som viser anten til eit gjeve vindauge eller det gjeldande dokumentet.

### Syntaks:

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

svc.GetDocument(windowname: uno): svc

### Parametrar:

windowname: Sjå definisjonane ovanfor. Viss dette argument manglar, vert det aktive vindauget brukt. UNO-objekt av typane com.sun.star.lang.XComponent eller com.sun.star.comp.dba.ODatabaseDocument vert også aksepterte. Så viss du sender ThisComponent eller ThisDatabaseDocument som argument, vert det oppretta ei ny teneste, anten SFDocuments.Document, Base eller Calc.

### Eksempel:

##### I Basic

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

##### I Python

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

Viss du ønskjer tilgang til namnet på det aktive vindauget, sjå eigenskapen ActiveWindow.

## Maximize

Maksimerer det aktive vindauget eller det gjevne vindauget.

### Syntaks:

svc.Maximize(windowname: str)

### Parametrar:

windowname: sjå definisjonane ovanfor. Viss dette argumentet manglar, vert det gjeldande vindauget maksimert.

### Eksempel:

##### I Basic

          ui.Maximize("Untitled 1")

##### I Python

         ui.Maximize("Untitled 1")

## Minimize

Minimerer det aktive vindauget eller det gjevne vindauget.

### Syntaks:

svc.Minimize(windowname: str)

### Parametrar:

windowname: sjå definisjonane ovanfor. Viss dette argumentet manglar, vert det gjeldande vindauget minimert.

### Eksempel:

##### I Basic

         ui.Minimize()

##### I Python

         ui.Minimize()

## OpenBaseDocument

Opnar eit LibreOffice Base-dokument som finst frå før. Metoden returnerer eit Base-objekt.

### Syntaks:

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

### Parametrar:

filnamn: Identifiserer fila som skal opnast. Namnet må følgja notasjonen SF_FileSystem.FileNaming .

registrationname: Namnet som vert brukt for å finna databasen i databaseregisteret. Dette argument vert ignorert viss filnamn <> "".

macroexecution: 0 = åtferda vert bestemt av brukaroppsettet, 1 = makroar er ikkje køyrbare, 2 = makroar er køyrbare. Standard er 0.

### Eksempel:

##### I Basic

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

##### I Python

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

For å gjera koden lettare å lesa, kan du bruka førehandsdefinerte konstantar for argumentet macroexecution som i eksempla ovanfor .

## OpenDocument (*)

Opnar eit LibreOffice-dokument som finst frå før med dei gjevne vala. Returnerer eit dokumentobjekt eller ein av underklassane i det. Metoden returnerer Ingenting (i BASIC) eller Ingen (i Python) viss opninga ikkje lukkast, sjølv om feilen kjem av feil brukarval.

### Syntaks:

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

### Parametrar:

filename: Identifiserer fila som skal opnast. Namnet må følgja FileNaming-notasjonen i tenesta FileSystem.

password: Vert brukt når dokumentet er verna. Viss passordet er feil eller manglar når dokumentet er passordverna, vert brukaren beden om å skriva inn passordet.

readonly: Standard = Usann.

hidden: viss Sann, opnar du det nye dokumentet i bakgrunnen (standard = Usann). Må brukast med varsemd sidan aktivering eller lukking seinare berre kan skje programmatisk.

macroexecution: 0 = åtferda vert bestemt av brukaroppsettet, 1 = makroar er ikkje køyrbare, 2 = makroar er køyrbare. Standard er 0.

filtername: Namnet på eit filter som skal brukast for å lasta inn dokumentet. Viss brukt, må filteret finnast.

filteroptions: Ein valfri streng med innstillingar for dette filteret.

### Eksempel:

##### I Basic

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

##### I Python

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

## Resize

Endrar storleiken og/eller flyttar det gjeldande vindauget. Manglande og negative argument vert ignorerte. Viss vindauget er minimert eller maksimert, kan du gjenoppretta det ved å kalla opp Resize utan argument.

### Syntaks:

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

### Parametrar:

left, top: Avstandar frå det øvste, venstre hjørne frå den øvre, venstre kanten av skjermen, i pikslar.

width, height: Nye dimensjonar for vindauget i pikslar.

### Eksempel:

I dei neste eksempla vert width (breidd) og height (høgd) for vindauget endra, medan top (oppe) og left (venstre) ikkje vert endra..

##### I Basic

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

##### I Python

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

For å endra storleiken på eit vindauge som ikkje er aktivt, må du aktivera det først med metoden Activate.

## RunCommand

Køyrer ein UNO-kommando i det gjeldande vindauget. Nokre typiske kommandoar er: Save, SaveAs, ExportToPDF, Undo, Copy, Paste, osv.

Kommandoar kan køyrast med eller utan argument. Argument vert ikkje validerte før kommandoen vert utført. Viss kommandoen eller argumenta i han er ugyldige, skjer det ingenting.

Du finn ei fullstendig liste over UNO-kommandoar som kan køyrast i LibreOffice på Wiki-sida Development/DispatchCommands.

### Syntaks:

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

### Parametrar:

command: Streng med UNO-kommandonamnet. Strengen skil mellom store og små bokstavar. Om du vil ha med prefikset ".uno:" er valfritt. Det vert ikkje kontrollert om sjølve kommandoen er gyldig. Viss det ikkje skjer noko etter at kommandoen er kalla opp, er han sannsynlegvis feil.

args: For kvart argument som skal sendast vidare til kommandoen, må du spesifisera eit par som inneheld namnet og verdien til argumentet.

### Eksempel:

##### I Basic

Det neste eksempelet køyrer kommandoen .uno:About i det gjeldande vindauget.

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

Nedanfor er eit eksempel som køyrer UNO-kommandoen .uno:BasicIDEAppear og sender dei nødvendige argumenta for å opna Basic IDE på ei bestemt linje i ein modul.

        ' Argument sende 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 å kalla opp kommandoen BasicIDEAppear utan argument vil opna Basic IDE.

##### I Python

        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å mogleg å kalla opp RunCommand ved å bruka nøkkelordargument:

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

Kvar LibreOffice-komponent har sitt eige sett med kommandoar tilgjengeleg. Ein enkel måte å læra kommandoar på er å gå til Verktøy → Tilpass → Tastatur. Når du held musepeikaren over ei oppføring i lista over Funksjonar kjem det opp ei hjelpeboble med den tilsvarande UNO-kommandoen.

## SetStatusbar (*)

Viser tekst og ei framdriftslinje på statuslinja i det gjeldande vindauget. Alle seinare oppkall i den same makrokøyringa refererer til same statuslinje i same vindauge, sjølv om vindauget ikkje er synleg. Eit oppkall utan argument tilbakestiller statuslinja til normaltilstanden.

### Syntaks:

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

### Parametrar:

text: Ein valfri tekst som skal visast framføre framdriftslinja.

percentage: eit valfritt framdriftsnivå mellom 0 og 100.

### Eksempel:

##### I Basic

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

##### I Python

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

## ShowProgressBar

Visar eit ikkje-modalt dialogvindauge. Spesifiser tittelen, den forklarande teksten og framdriftsprosenten som skal visast på ei framdriftslinje. Dialogvindauget er synleg til metoden vert kalla utan argument, eller at brukaren lukkar dialogvindauget manuelt.

### Syntaks:

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

### Parametrar:

title: Tittelen som vert vist øvst i dialogvindauget. Standard = "ScriptForge".

text: Ein valfri tekst som skal visast over framdriftslinja.

percentage: eit valfritt framdriftsnivå mellom 0 og 100.

### Eksempel:

##### I Basic

          Dim i As Integer
          For i = 0 To 100
              ui.ShowProgressBar("Window Title", "Progress ..." & i & "/100", i)
              Wait 50
          Next i
          ' Lukker vindauget med framdriftslinja
          ui.ShowProgressBar

##### I Python

         from time import sleep
         for i in range(101):
             ui.ShowProgressBar("Window Title", "Progress ... " + str(i) + "/100", i)
             sleep(0.05)
         # Lukker vindauget med framdriftslinja
         ui.ShowProgressBar()

## WindowExists

Returnerer True viss det gjevne vindauget kunne identifiserast.

### Syntaks:

svc.WindowExists(windowname: str): bool

### Parametrar:

windowname: sjå definisjonane ovanfor.

### Eksempel:

##### I Basic

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

##### I Python

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

Liknande emne

Tenesta ScriptForge.Basic

SFDocuments.Calc

Tenesta SFDocuments.Document