Tjenesten ScriptForge.UI

Indhold
Indholdsfortegnelse 🔎︎

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

- 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) og OpenDocument (åbn dokument), beskrevet herunder, genererer dokument-objekter. Når et vindue indeholder et dokument, repræsenterer en forekomst af klassen Document dette dokument. Et modsat eksempel: et Basic IDE er ikke et dokument, men er et vindue i vor 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

##### I Basic

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

##### I Python

        from scriptforge import CreateScriptService
        svcUI = 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 nul-længde streng.
Documents | Ja | String array | Listen over aktuelt åbne dokumenter. Specialvinduer ignoreres. Denne liste består af en nul-baseret en-dimensionel matrix af enten filnavne (i SF_FileSystem.FileNaming-notation) eller af titler på ikke-gemte dokumenter.

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

         svcUI = CreateScriptService("UI")
         sBasic = CreateScriptService("Basic")
         openDocs = svcUI.Documents()
         strDocs = "\n".join(openDocs)
         sBasic.MsgBox(strDocs)

Liste over metoder i tjenesten UI (brugerflade)
Activate CreateBaseDocument CreateDocument (*) GetDocument | Maximize Minimize OpenBaseDocument OpenDocument (*) | Resize 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:

vinduesnavn: se definitionerne ovenfor.

### Eksempel:

##### I Basic

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

##### I Python

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

## CreateBaseDocument

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

### Syntaks:

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

### Parametre:

filnavn: Identificerer swn fil, der skal oprettes. Den skal følge SF_FileSystem.FileNaming notationen. Hvis filen allerede eksisterer, overskrives den uden advarsel.

embeddeddatabase : Enten "HSQLDB" (standard) eller "FIREBIRD".

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

### Eksempel:

##### I Basic

          Dim myBase As Object
          Set myBase = ui.CreateBaseDocument("C:\Databases\MyBaseFile.odb", "FIREBIRD")

##### I Python

         myBase = svcUI.CreateBaseDocument(r"C:\Databases\MyBaseFile.odb", "FIREBIRD")

## CreateDocument (*)

Opret et nyt LibreOffice-dokument af en given type eller baseret på en given skabelon. Metoden returnerer et dokumentobjekt.

### Syntaks:

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

### Parametre:

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

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.

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 ekseempler herunder opretter det første kald af metoden CreateDocument wet 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 = svcUI.CreateDocument("Calc")
         FSO = CreateScriptService("FileSystem")
         myDoc2 = svcUI.CreateDocument(templatefile = FSO.BuildPath(FSO.TemplatesFolder, "personal/CV.ott"))

## GetDocument

Returnerer et dokument-objekt, der refererer til enten det aktive vindue eller det givne vindue.

### Syntaks:

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

### Parametre:

windowname: Se definitionerne ovenfor. Hvis dette argument mangler, bruges det aktive vindue.

### Eksempel:

##### I Basic

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

##### I Python

         myDoc = svcUI.GetDocument(r"C:\Documents\My file.odt")

For at tilgå navnet på det aktuelt aktive vindue, henviser du til egenskaben ActiveWindow.

## Maximize

Maksimerer det aktive vindue eller det givne vindue.

### Syntaks:

svc.Maximize(windowname: str)

### Parametre:

vinduesnavn: se definitionerne ovenfor. Hvis dette argument mangler, maksimeres det aktive vindue.

### Eksempel:

##### I Basic

          ui.Maximize("Untitled 1")

##### I Python

         svcUI.Maximize("Untitled 1")

## Minimize

Minimerer det aktive vindue eller det givne vindue.

### Syntaks:

svc.Minimize(windowname: str)

### Parametre:

vinduesnavn: se definitionerne ovenfor. Hvis dette argument mangler, minimeres det aktive vindue.

### Eksempel:

##### I Basic

         ui.Minimize()

##### I Python

         svcUI.Minimize()

## OpenBaseDocument

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

### Syntaks:

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

### Parametre:

filnavn: Identificerer den fil, der skal åbnes. Det skal følge SF_FileSystem.FileNaming-notationen. Hvis filen allerede findes, overskrives den uden advarsel

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

makro-udførelse: 0 = adfærd er defineret af brugerkonfigurationen, 1 = makroer kan ikke udføres, 2 = makroer kan udføres.

### Eksempel:

##### I Basic

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

##### I Python

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

For at forbedre kodens læselighed kan du bruge foruddefinerede konstanter i argumentet macroexecution (makroudførelse), som i eksemplerne ovenfor.

## OpenDocument (*)

Åbner et eksisterende LibreOffice-dokument med de opgivne indstillinger. Returnerer et dokument-objekt eller en af dets underklasser. Metoden returnerer Nothing (Intet) (i Basic) / None (Ingen) (i Python), hvis åbningen mislykkedes, selv når fejlen skyldes en brugerbeslutning.

### Syntaks:

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

### Parametre:

filnavn: Identificerer filen, der skal åbnes. Det skal følge FileNaming-notation i tjenesten FileSystem .

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.

skrivebeskyttet: Standard = False (falsk).

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.

makro-udførelse: 0 =adfærd er defineret af brugerkonfiguration, 1 = makroer kan ikke udføres, 2 = makroer kan udføres.

filternavn: Navnet på et filter, der skal bruges til at indlæse dokumentet. Hvis det findes, skal filtret findes.

filter-indstillinger: En valgfri indstillings-streng, der er associeret med filteret.

### Eksempel:

##### I Basic

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

##### I Python

         svcUI.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 (Juster størrelse) uden argumenter det.

### Syntaks:

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

### Parametre:

venstre, øverst: Afstande fra det øverste-venstre hjørne fra den øverste og den venstre kan af skærmen i pixler.

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

##### I Python

         svcUI.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 (Aktiver).

## SetStatusbar (*)

Vis en tekst og en fremdriftslinje i det aktive vindues statuslinje. Ethvert efterfølgende kald i den samme makrokørsel 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:

tekst: En valgfri tekst, der skal vises foran statuslinjen.

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):
             svcUI.SetStatusbar("Test:", i)
             sleep(0.05)
         svcUI.SetStatusbar()

## ShowProgressBar

Viser et ikke-modalt dialogfelt. Angiver dets titel, en forklarende tekst og en fremskridts-procentdel, der skal præsentereres 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: str = -1)

### Parametre:

titel: Titlen, der visves øverst i dialogfeltet. Standard = "ScriptForge".

tekst: En valgfri tekst, der skal vises over statuslinjen.

peocentdel: 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 vinduet Statuslinje
          ui.ShowProgressBar

##### I Python

         from time import sleep
         for i in range(101):
             svcUI.ShowProgressBar("Window Title", "Progress ... " + str(i) + "/100", i)
             sleep(0.05)
         # Lukker vinduet Statuslinje
         svcUI.ShowProgressBar()

## WindowExists

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

### Syntaks:

svc.WindowExists(windowname: str): bool

### Parametre:

vinduesnavn: se definitionerne herover.

### Eksempel:

##### I Basic

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

##### I Python

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

Relaterede emner

Tjenesten SFDocuments.Document