ScriptForge.UI-tjenesten

Indhold

# Tjenesten ScriptForge.UI (brugerflade)

Tjenesten UI (User Interface = brugerflade) forenkler identifikationen og håndteringen af de forskellige vinduer, der udgør hele LibreOffice-programet.

- Windows selection (vinduesudvælgelse)

- Flytning og størrelsesændring af vinduer

- Statuslinjens indstillinger

- Visning af en flydende fremgangsvisning

- Oprettelse af nye vinduer

- Adgang til de underliggende "dokumenter"

Tjenesten UI er startpunktet til åbning af, oprettelse af og tilgang til indholdet i nye eller eksisterende dokumenter fra et bruger-script.

## Definitioner

### WindowName

Et vindue kan udpeges på forskellige måder:

- en fuld sti og filnavn

- den sidste komponent i det fulde filnavn eller endda kun den sidste komponent uden dens suffiks

- vinduets titel

- ved nye dokumenter, noget som ligner "Unavngivet 1"

- et af specialvinduerne "BASICIDE" (Basic IDE) og "WELCOMESCREEN" (velkomstskærm)

Vinduets navn bruger både Store og små bogstaver.

### Objektet Document

Metoderne CreateDocument (Opret_dokument), CreateBaseDocument (Opret_basedokument), GetDocument (Hent_dokument), OpenBaseDocument (Åbn_basedokument) og OpenDocument (Åbn_dokument), beskrevet nedenfor, genererere dokumentobjekter. Når et vindue indeholder et dokument, repræsenterer en instans af klassen Document dette dokument. Et modeksempel: Basic IDE'en er ikke et dokument men et vindue i vores terminologi. Derudover har et dokument en type: Calc, Impress, Writer, ...

De specifikke egenskaber og metoder, der kan anvendes på dokumenter er implementeret i en dokument-klasse.

Implementeringen af objektklassen document udføres i det tilknyttede bibliotek SFDocuments. Se dets tjeneste "Document" (dokument).

## Kald af tjeneste

Før brug af tjenesten UI skal biblioteket ScriptForge være indlæst eller importeret:

• Basic-makroer kræver, at biblioteket ScriptForge indlæses med følgende udtryk:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
• Python-scripts kræver import af scriptforge-modulet:
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")

## Egenskaber

Navn | Skrivebeskyttet | Type | Beskrivelse
--- | --- | --- | ---
ActiveWindow | Ja | String | et gyldigt og unikt WindowName (vinduesnavn) til det aktuelt aktive vindue. Når vinduet ikke kan identificeres, returneres en tom streng, "".
Height | Ja | Integer | Returnerer højden af det aktive vindue i pixels.
Width | Ja | Integer | Returnerer bredden af det aktive vindue i pixels.
X | Ja | Integer | Returnerer X-koordinaten for det aktive vindue, som er afstanden til venstre kant af skærmen i pixels.
Y | Ja | Integer | Returnerer Y-koordinaten for de aktive vindue, hvilket er afstanden til overkanten af skærmen i pixels. Denne værdi kompenserer ikke for vinduesdekorationer tilføjet af dit operativsystem, så selv når vinduet er maksimeret, er denne værdi måske ikke nul.

## Konstanter

Navn | Værdi | Beskrivelse
--- | --- | ---
MACROEXECALWAYS | 2 | Makroer udføres altid
MACROEXECNEVER | 1 | Makroer udføres aldrig
MACROEXECNORMAL | 0 | Makro-udførelse afhænger af brugerindstillinger

### Eksempel:

Eksemplet herunder viser et MsgBox (Beskedfelt) med navnene på alle aktuelt åbne dokumenter.

##### 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 metoder i tjenesten UI (brugerflade)
Activate CreateBaseDocument CreateDocument (*) Documents GetDocument | Maximize Minimize OpenBaseDocument OpenDocument (*) Resize | RunCommand SetStatusBar (*) ShowProgressBar WindowExists

Bemærk undtagelsesvis, at metoder, der er mærket med (*), ikke kan anvendes i Base-dokumenter.

## Activate

Gør det bestemte vindue aktivt. Metoden returnerer True (sand), hvis det givne vindue bliver fundet og kan aktiveres. Der er ikke nogen ændring i den aktuelle brugerflade, vis intet vindue matcher udvælgelsen.

### Syntaks:

svc.Activate(windowname: str): bool

### Parametre:

windowname (vinduesnavn): Se definitionerne ovenfor.

### Eksempel:

##### I Basic

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

##### I Python

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

## CreateBaseDocument

Opretter og gemmer et nyt LibreOffice Base-dokument, der indlejrer en tom database af den givne type. Metoder returnerer en instans af tjenesten Document.

### Syntaks:

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

### Parametre:

filename (filnavn): Identificerer filen, som skal oprettes. Filnavnet skal følge SF_FileSystem.FileNaming-notationen. Hvis filen allerede eksisterer, bliver den overskrevet uden advarsel.

embeddeddatabase (indlejret_database): Enten "HSQLDB" (standard), "FIREBIRD" eller "CALC".

registrationname (registreringsnavn): Navnet, der bruges til at gemme den nye database i databasens register. Når = "" (standard), sker der ingen registrering. Hvis navnet allerede eksisterer, overskrives det uden advarsel.

calcfilename (calc-filnavn): Kun når embeddeddatabase (indlejret_database) = "CALC", repræsenterer calcfilename filen , der indeholder tabellerne, som Calc-regneark. Filen skal findes, eller sættes der et fejlflag.

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

Opretter et nyt LibreOffice-dokument af en given type eller basret på en given skabelon. Metoden returnerer en instans af dokumentklassen eller en af dens underklasser (Calc, Writer).

### Syntaks:

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

### Parametre:

documenttype (dokumenttype): "Calc", "Writer", osv. Hvis den mangler, skal argumentet templatefile (skabelonfil) være tilstede.

templatefile (skabelonfil): Det fulde FileName (filnavn) på den skabelon, det nye dokument skal bygges på. Hvis filen ikke eksisterer, ignoreres argumentet. Tjenesten FileSystem (filsystem) service sørger for egenskaberne TemplatesFolder (Skabelonmappe) og UserTemplatesFolder (Bruger_skabelonmappe), der hjælper med at bygge argumentet.

hidden (skjult): Hvis True (sand), åbner du det nye dokument i baggrunden (standard = False (falsk)). Skal bruges med forsigtighed: aktivering eller lukning senere hen kan kun ske fra programmet.

### Eksempel:

I begge eksempler herunder opretter det første kald af metoden CreateDocument et tomt Calc-dokument, mens det andet opretter et dokument fra en skabelonfil.

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

Listen over de dokumenter, som aktuelt er åbne. Specielle vinduer ignoreres. Listen består af et en-dimensionalt array med 0 som første indeks, der indeholder filnavne – med brug af ScriptForge.FileSystem.FileNaming-notation – eller vinduestitler for dokumenter, som endnu ikke har været gemt.

### Syntaks:

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

### Eksempel:

I begge eksempler herunder kan metoden returnere et tomt array, hvis ingen dokumenter er åbne.

##### I Basic

          Dim docList As Variant
          docList = ui.Documents

##### I Python

         docList = ui.Documents()

## GetDocument

Returnerer en instans af Dockument-klassen eller en af dens underklasser (Calc, Writer, Base, FormDocument), som refererer til enten et givet vindue eller det aktive dokument.

### Syntaks:

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

svc.GetDocument(windowname: uno): svc

### Parametre:

windowname (vinduesnavn): Se definitionerne ovenfor. Hvis dette argument mangler, bruges det aktive vindue. UNO-objekter af typerne com.sun.star.lang.XComponent eller com.sun.star.comp.dba.ODatabaseDocument accepteres også. På denne måde opretter videregivelse af ThisComponent (denne_komponent) eller ThisDatabaseDocument (dette_database-dokument) som argument et nyt SFDocuments.Document (SF-dokumenter.dokument), en ny Base (database) eller en ny Calc service (Calc-tjeneste).

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

For at tilgå navnet på det aktuelt aktive vindue, se egenskaben ActiveWindow.

## Maximize

Maksimerer det aktive vindue eller det givne vindue.

### Syntaks:

svc.Maximize(windowname: str)

### Parametre:

windowname (vinduesnavn): Se definitionerne ovenfor. Hvis dette argument mangler, maksimeres det aktive vindue.

### Eksempel:

##### I Basic

          ui.Maximize("Untitled 1")

##### I Python

         ui.Maximize("Untitled 1")

## Minimize

Minimerer det aktive vindue eller det givne vindue.

### Syntaks:

svc.Minimize(windowname: str)

### Parametre:

windowname (vinduesnavn): Se definitionerne ovenfor. Hvis dette argument mangler, minimeres det aktive vindue.

### Eksempel:

##### I Basic

         ui.Minimize()

##### I Python

         ui.Minimize()

## OpenBaseDocument

Åbner et eksisterende LibreOffice Base-dokument. Metoden returnerer et Base-objekt.

### Syntaks:

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

### Parametre:

filename (filnavn): Identificerer filen, der skal åbnes. Filnavnet skal følge notationen SF_FileSystem.FileNaming.

registrationname (registreringsnavn): Navnet, der bruges til at finde databasen i databaseregistret. Det ignoreres, hvis FileName <> "".

macroexecution (makroudførelse): 0 = opførsel er bestemt af brugerindstillingerne, 1 = makroer kan ikke udføres, 2 = makroer kan udføres. 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 at øge læseligheden af koden kan du bruge forhåndsdefinerede konstanter til argumentet macroexecution, som vist i eksemplerne ovenfor.

## OpenDocument (*)

Åbner et eksisterende LibreOffice-dokument med de givne indstillinger. Returnerer et dokumentobjekt (Document) eller en af dets underklasser. Denne metode returnerer Nothing (i Basic) eller None (i Python), hvis åbning ikke lykkes, selv når det skyldes brugerens beslutning.

### Syntaks:

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

### Parametre:

filename (filnavn): Identificerer filen, der skal åbnes. Filnavnet skal følge FileNaming-notationen fra FileSystem-tjenesten.

password (adgangskode): Til brug, når dokumentet er beskyttet. Hvis den er forkert eller mangler, når dokumentet er beskyttet, bliver brugeren bedt om at indtaste en adgangskode.

readonly (skrivebeskyttet): Standard = False (falsk).

hidden (skjult): Hvis True (sand), åbner du dokumentet i baggrunden (standard = False (falsk)). Bør bruges med forsigtighed: aktivering eller lukning kan kun ske fra programmet.

macroexecution (makroudførelse): 0 = opførsel er bestemt af brugerindstillingerne, 1 = makroer kan ikke udføres, 2 = makroer kan udføres. Standard er 0.

filtername (filternavn): Navnet på et filter, der skal bruges til at indlæse dokumentet. Hvis argumentet angives, skal filteret eksistere.

filteroptions (filterindstillinger): En valgfri streng med indstillinger, der passer til 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

Ændrer størrelse på og/eller flytter det aktive vindue. Manglende og negative argumenter ignoreres. Hvis vinduet er minimeret eller maksimeret, gendanner kald af Resize (ændre størrelse) uden argumenter det.

### Syntaks:

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

### Parametre:

left, top (venstre, øverst): Afstand fra skærmkanten og skærmtoppen til det vinduets øverste venstre hjørne, angivet i pixler.

width, height (bredde, højde): Vinduets nye dimensioner i pixler.

### Eksempel:

I de følgende de følgende eksempler ændres vinduets width (bredde) og height (højde), mens top (øverst) og left (venstre) efterlades uændrede.

##### I Basic

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

##### I Python

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

For at ændre størrelse på et vindue, der ikke er aktivt, aktiverer du det først med metoden Activate (Aktivér).

## RunCommand

Kører en UNO-kommando i det aktuelle vindue. Nogle få typiske kommandoer er: Gem, Gem som, Eksportér til PDF, Fortryd, Kopiér, Indsæt, og så videre.

Kommandoer kan køres med eller uden argumenter. Argumenter valideres ikke, før kommandoen køres. Hvis kommandoen eller dens argumenter er ugyldige, sker der intet.

Se en komplet liste over UNO-kommandoer, der kan køres i LibreOffice på Wikisiden Development/DispatchCommands.

### Syntaks:

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

### Parametre:

command (kommando): Streng, der indeholder UNO-kommandoens navn, med skelnen mellem store og små bogstaver. Medtagelse af forstavelsen ".uno:" i kommandoen er valgfrit. Selve kommandoen tjekkes ikke for korrekthed. Hvis der ikke sker noget efter kommandokaldet, er kommandoen er sandsynligvis forkert.

args (argumenter): For hvert argument, der skal videregives til kommandoen, angiver du et par, der indeholder argumentets navn og værdi.

### Eksempel:

##### I Basic

Det følgende eksempel kører kommandoen .uno:About i det aktuelle vindue.

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

Herunder er der et eksempel, der kører UNO-kommandoen .uno:BasicIDEAppear og videregiver de argumenter, der er nødvendige for at åbne Basic IDE'et på en angiven linje i modulet.

        ' Argumenter videregivet 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)

Bemærk, at kald af kommandoen BasicIDEAppear uden argumenter kun åbner Basic IDE'en.

##### 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å muligt at kæde RunCommand (kør_kommando) med nøgleords-argumenter:

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

Hver LibreOffice-komponent har sit eget sæt af tilgængelige kommandoer. En nem måde at lære kommandoer på er at gå til Funktioner ▸ Tilpas ▸ Tastatur. Når du placerer musen over en funktion på listen Funktion, vises et værktøjstip med den tilsvarende UNO-kommando.

## SetStatusbar (*)

Vis en tekst og en fremdriftslinje i det aktive vindues statuslinje. Ethvert efterfølgende kald i den samme makroafvikling refererer til den samme statuslinje i det samme vindue, også selv om vinduet ikke mere er synligt. Et kald uden argumenter nulstiller statuslinjen til dens normale tilstand.

### Syntaks:

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

### Parametre:

text (tekst): En valgfri tekst, der skal vises foran fremgangsvisningen.

percentage (procentdel): en valgfri fremskrifts-procentdel mellem 0 og 100.

### Eksempel:

##### I Basic

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

##### I Python

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

## ShowProgressBar

Viser et ikke-modalt dialogfelt. Angiver dets titel, en forklarende tekst og en fremskridts-procentdel, der skal præsenteres på en statuslinje. Dialogen forbliver synlig, indtil et kald af metoden uden argumenter eller indtil brugeren manuelt lukker dialogen.

### Syntaks:

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

### Parametre:

title (titel): Titlen, der vises øverst i dialogfeltet. Standard = "ScriptForge".

text (tekst): En valgfri tekst, der skal vises over fremgangsvisningen.

percentage (procentdel): En valgfri grad af fremskrift mellem 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 fremgangsvisnings-vinduet
          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 fremgangsvisnings-vinduet
         ui.ShowProgressBar()

## WindowExists

Returnerer True (sand), hvis det givne vindue kunne identificeres.

### Syntaks:

svc.WindowExists(windowname: str): bool

### Parametre:

windowname (vinduesnavn): Se definitionerne ovenfor.

### Eksempel:

##### I Basic

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

##### I Python

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

Relaterede emner

tjenesten ScriptForge.Basic

SFDocuments.Calc

Tjenesten SFDocuments.Document