ScriptForge.Basic-tjenesten

Indhold

# tjenesten ScriptForge.Basic

Tjenesten ScriptForge.Basic tilbyder en samling af LibreOffice Basic-metoder til kørsel i en Python-kontekst. Tjenesten Basics metoder reproducerer de indbyggede Basic-funktioners præcise syntaks og adfærd.

Typisk eksempel:

       bas.MsgBox('Vis denne tekst i et meddelsesesfelt fra et Python-script')

Tjenesten ScriptForge.Basic er begrænset til Python-scripts.

## Kald af tjeneste

Før brug af tjenesten Basic importerer du metoden CreateScriptService() fra moduletscriptforge:

        from scriptforge import CreateScriptService
        bas = CreateScriptService("Basic")

## Egenskaber

Navn | Skrivebeskyttet | Type | Beskrivelse
--- | --- | --- | ---
MB_OK, MB_OKCANCEL, MB_RETRYCANCEL, MB_YESNO, MB_YESNOCANCEL | Ja | Integer | Værdier: 0, 1, 5, 4, 3
MB_ICONEXCLAMATION, MB_ICONINFORMATION, MB_ICONQUESTION, MB_ICONSTOP | Ja | Integer | Værdier: 48, 64, 32, 16
MB_ABORTRETRYIGNORE, MB_DEFBUTTON1, MB_DEFBUTTON2, MB_DEFBUTTON3 | Ja | Integer | Værdier: 2, 128, 256, 512
IDABORT, IDCANCEL, IDIGNORE, IDNO, IDOK, IDRETRY, IDYES | Ja | Integer | Værdier: 3, 2, 5, 7, 1, 4, 6 Konstanter, der peger på den valgte knap i MsgBox.
StarDesktop | Ja | UNO objekt | Returnerer det StarDesktop-objekt, som repræsenterer LibreOffice-programmet.
ThisComponent | Ja | UNO objekt | Hvis den aktuelle komponent refererer til et LibreOffice-dokument, returnerer denne metode det UNO-objekt, som returnerer dokumentet. Når den aktuelle komponent ikke svarer til et dokument, returnerer denne egenskab None.
ThisDatabaseDocument | Ja | UNO objekt | Hvis scriptet bliver udført fra et Base-dokument eller en af underkomponenterne, så returnerer denne metode hovedkomponenten af Base-instansen. Denne egenskab returnerer None i andre tilfælde.

Liste over metoder i tjenesten Basic
CDate CDateFromUnoDateTime CDateToUnoDateTime ConvertFromUrl ConvertToUrl CreateUnoService CreateUnoStruct DateAdd | DateDiff DatePart DateValue Format GetDefaultContext GetGuiType GetPathSeparator GetSystemTicks | GlobalScope.BasicLibraries GlobalScope.DialogLibraries InputBox MsgBox Now RGB Xray

## CDate

Konverterer et numerisk udtryk eller en streng til et standard datetime.datetime Python-objekt.

Denne metode udsætter den indbyggede Basic-funktion CDate for Python-scripts.

### Syntaks:

svc.CDate(expression: any): obj

### Parametre:

udtryk: et numerisk udtryk eller en streng, der repæsenterer en dato.

Når du konverterer et streng-udtryk, må dato og tid være skrevet enten i et af dato-genkendelsesmønstrene defineret af dine lokalitetsindstilligner (se LibreOffice ▸ PræferencerFunktioner ▸ Indstillinger ▸ Sprog og lokalitetsindstillinger ▸ Generelt) eller i ISO-datoformat (i øjeblikket accepteres kun ISO-format med bindestreger, f.eks. bliver "2012-12-31" accepteret). I talværdier repræsenterer værdier til venstre for kommaet (decimaltegnet) dato, begyndende fra 31. december 1899. Værdier til højre for kommaet repræsenterer klokkeslættet.

### Eksempel:

        d = bas.CDate(1000.25)
        bas.MsgBox(str(d)) # 1902-09-26 06:00:00
        bas.MsgBox(d.year) # 1902

## CDateFromUnoDateTime

Konverterer en UNO dato/klokkeslæt-representation til et standard datetime.datetime Python-objekt.

### Syntaks:

svc.CDateFromUnoDateTime(unodate: uno): obj

### Parametre:

unodate: Et UNO dato/klokkeslæt-objekt af følgende typer: com.sun.star.util.DateTime, com.sun.star.util.Date eller com.sun.star.util.Time

### Eksempel:

Det følgende eksempel opretter et com.sun.star.util.DateTime-objekt og konverterer det til et datetime.datetime Python-objekt.

        uno_date = bas.CreateUnoStruct('com.sun.star.util.DateTime')
        uno_date.Year = 1983
        uno_date.Month = 2
        uno_date.Day = 23
        new_date = bas.CDateFromUnoDateTime(uno_date)
        bas.MsgBox(str(new_date)) # 1983-02-23 00:00:00

## CDateToUnoDateTime

Konverterer en dato-repræsentation til et com.sun.star.util.DateTime-objekt.

### Syntaks:

svc.CDateToUnoDateTime(date: obj): uno

### Parametre:

dato: Et Python dato/klokkeslæt-objekt af en af følgende typer: datetime.datetime, datetime.date, datetime.time, float (time.time) eller time.struct_time.

### Eksempel:

        from datetime import datetime
        current_datetime = datetime.now()
        uno_date = bas.CDateToUnoDateTime(current_datetime)
        bas.MsgBox(str(uno_date.Year) + "-" + str(uno_date.Month) + "-" + str(uno_date.Day))

## ConvertFromUrl

Returnerer en systemsti filnavn til den givne file: URL.

### Syntaks:

svc.ConvertFromUrl(url: str): str

### Parametre:

url: En absolut file: URL.

### Returværdi:

Et systemsti-filnavn.

### Eksempel:

        filename = bas.ConvertFromUrl( "file:///C:/Program%20Files%20(x86)/LibreOffice/News.txt")
        bas.MsgBox(filename)

## ConvertToUrl

Returnerer file: URL til den givne systemsti.

### Syntaks:

svc.ConvertToUrl(systempath: str): str

### Parametre:

systemsti: Navnet på en systemfil som en streng.

### Returværdi:

A file: URL som en streng.

### Eksempel:

        url = bas.ConvertToUrl( 'C:\Program Files(x86)\LibreOffice\News.txt')
        bas.MsgBox(url)

## CreateUnoService

Instantierer en UNO-tjeneste med ProcessServiceManager.

### Syntaks:

svc.CreateUnoService(servicename: str): uno

### Parametre:

servicename: Et fuldt kvalificeret tjenestenavn som for eksempel com.sun.star.ui.dialogs.FilePicker eller com.sun.star.sheet.FunctionAccess.

### Eksempel:

        dsk = bas.CreateUnoService('com.sun.star.frame.Desktop')

## CreateUnoStruct

Returnerer en instans af en UNO-struktur af den angivne type.

### Syntaks:

svc.CreateUnoStruct(unostructure: str): uno

### Parametre:

unostructure: Et fuldt kvalificeret strukturnavn som com.sun.star.beans.Property eller com.sun.star.util.DateTime.

### Eksempel:

        date_struct = CreateUnoStruct('com.sun.star.util.DateTime')

## DateAdd

Tilføjer en dato eller tidsinterval til en given dato/klokkeslæt et antal gange og returnerer den resulterende dato.

### Syntaks:

svc.DateAdd(interval: str, number: num, date: datetime): datetime

### Parametre:

interval: Et strengudtryk fra den følgende tabel, der angiver datoen eller tidsintervallet.

interval (strengværdi) | Forklaring
--- | ---
yyyy | År
q | Kvartal
m | Måned
y | Dag i året
w | Ugedag
ww | Uge i året
d | Dag
h | Time
n | Minut
s | Sekund

antal: Et numerisk udtryk, der angiver hvor ofte værdien interval skal tilføjes, når den er positiv, er trækkes fra, når når den er negativ.

dato: En given datetime.datetime-værdi, interval-værdien vil, blive lagt number (antal) gange til denne datetime.datetime-værdi.

### Returværdi:

En datetime.datetimeværdi.

### Eksempel:

        dt = datetime.datetime(2004, 1, 31)
        dt = bas.DateAdd("m", 1, dt)
        print(dt)

## DateDiff

Returnerer antallet af dags- eller tids-intervaller mellem to givne dato-/klokkeslæt-værdier.

### Syntaks:

svc.DateDiff(interval: str, date1: datetime, date2: datetime, firstdayofweek = 1, firstweekofyear = 1): int

### Parametre:

interval: Et strengudtryk, der angiver datointervallet, som vist i metoden DateAdd ovenfor.

dato1, dato2: De to datetime.datetime-værdier, der skal sammenlignes.

førstedagiugen: Et valgfrit parameter, der angiver den dag, ugen begynder. An optional parameter that specifies the starting day of a week.

værdien førstedagiugen | Forklaring
--- | ---
0 | Brug systemets standardværdi
1 | Søndag (standard)
2 | Mandag
3 | Tirsdag
4 | Onsdag
5 | Torsdag
6 | Fredag
7 | Lørdag

førsteugeiåret: En valgfri parameter, der angiver den uge året begynder.

værdien førsteugeiåret | Forklaring
--- | ---
0 | Brug systemets standardværdi
1 | Uge 1 er ugen med 1. januar
2 | Uge 1 er den første uge, som indeholder fire eller flere dage af året
3 | Uge 1 er den første uge, som kun indeholder dage fra det nye år

### Returværdi:

Et tal.

### Eksempel:

        date1 = datetime.datetime(2005,1, 1)
        date2 = datetime.datetime(2005,12,31)
        diffDays = bas.DateDiff('d', date1, date2)
        print(diffDays)

## DatePart

Funktionen DatePart returnerer en angivet del af datoen.

### Syntaks:

svc.DatePart(interval: str, date: datetime, firstdayofweek = 1, firstweekofyear = 1): int

### Parametre:

interval: Et strengudtryk, der angiver datointervallet, som vist i metoden DateAdd ovenfor.

dato: Den dato/det klokkeslæt, hvorfra resultatet beregnes.

førstedagiugen, førsteuge i året: valgfrie parametre, der angiver henholdsvis ugens føreste dag og årets første uge som forklaret ovenfor i metoden DateDiff.

### Returværdi:

Den udtrukne del af den/det givne dato/klokkeslæt

### Eksempel:

        print(bas.DatePart("ww", datetime.datetime(2005,12,31)
        print(bas.DatePart('q', datetime.datetime(1999,12,30)

## DateValue

Beregner en datoværdi fra en datostreng.

### Syntaks:

svc.DateValue(date: str): datetime

### Parametre:

dato: En streng, der indeholder den dato, der bliver konverteret til et Dato-objekt.

Strengen sendt til DateValue skal udtrykkes i et af dato-formaterne defineret af dine lokalitetsindstilligner (se LibreOffice ▸ PræferencerFunktioner ▸ Indstillinger ▸ Sprog og lokalitetsindstillinger ▸ Generelt) eller brug ISO-datoformatet "åååå-mm-dd" (år, måned og dag adskilt af bindestreger).

### Returværdi:

Den beregnede dato.

### Eksempel:

        dt = bas.DateValue("23-02-2011")
        print(dt)

## Format

Konverterer et tal til en streng og formaterer den derefter i det format, du angiver.

### Syntaks:

svc.Format(expression: any, format = ''): str

### Parametre:

udtryk: Numerisk udtryk, som du vil konvertere til en formateret streng.

format: Streng, der angiver tallets formateringskode. Hvis format er udeladt, virker funktionen Format ligesom funktionen LibreOffice Basic Str().

### Returværdi:

Tekststreng.

### Formaterer koder

Følgende liste beskriver de koder, du kan bruge til at formatere et numerisk udtryk:

0: Hvis expression har et ciffer på nullets plads i koden format, vises cifret, ellers vises et nul.

Hvis expression har færre cifre end antallet af nuller i koden format, (på den ene eller anden side af decimalskilletegnet), vises foran- eller efterstillede nuller. Hvis expression har flere cifre til venstre for decimalskilletegnet end antallet af nuller i koden format, vises yderligere cifre uden formatering.

Decimalpladser i expression afrundes efter antallet af nuller, der ses efter decimalskilletegnet i koden format.

#: Hvis expression indeholder et ciffer på pladsholderen #s placering i koden format, vises cifret, ellers vises ingenting på denne placering.

Dette symbol virker ligesom 0, bortset fra, at foran- eller efterstillede nuller ikke vises, hvis der er flere #-tegn i koden format end tegn i expression. Kun de relevante cifre i expression vises.

.: Decimalpladsholderen bestemmer antal decimaler til venstre og højre for decimaltegnet.

Hvis koden format kun indeholder # pladholdere til venstre for dette symbol, begynder tal mindre en 1 med et decimalskilletegn. For altid at få vist et foranstillet nul ved brøktal bruger du 0 som en pladsholder for det første ciffer til venstre for decimalskilletegnet.

%: Multiplicerer expressionmed 100 og indsætter et procentegn (%), hvor expression vises i koden format.

E- E+ e- e+ : Hvis koden format indeholder mindst en ciffer-pladsholder (0 eller #) til højre for symbolet E-, E+, e-, eller e+, formateres expression i videnskabeligt eller eksponentielt format. Bogstavet E eller e indsætts mellem tallet og eksponenten. Antallet af pladsholdere for cifre til højre for symbolet bestemmer antallet af cifre i eksponenten.

Hvis eksponenten er negativ, bliver et minustegn vist umiddelbart før en eksponent med E-, E+, e-, e+. Hvis eksponenten er positiv, bliver et plustegn kun vist før eksponenter med E+ eller e+.

Tusindtalsskilletegnet vises, hvis koden format indeholder skilletegnet omgivet af ciffer-pladsholdere (0 eller #).

Brug af et punktum som et tusinde- og decimaltegn afhænger af regionsindstillingen. Brug altid et punktum som decimaltegn, når du indtaster et tal direkte i Basic-kildekode. Det specifikke tegn, der bliver vist som decimaltegn, afhænger af talformatet i dine systemindstillinger.

- + $ ( ) mellemrum: Et plus (+), et minus (-), et dollartegn ($), et emllemrum, eller klammer, der skrives direkte i koden format vises som et bogstaveligt tegn.

For at vise andre tegn end de der er opført her, skal du indlede det med en bagstreg (\), eller omgive det med anførselstegn (" ").

\ : Den omvendte skråstreg viser det næste tegn i koden format.

Tegn i koden format, der har en speciel betydning, kan kun vises som bogstavelige tegn, hvis der står en skråstreg foran. Skråstregen selv vises ikke, med mindre du indtaster en dobbelt omvendt skråstreg (\\) i formatkoden.

De tegn, der skal have foranstillet en bagstreg i formatkoden for at blive vist som bogstavelige tegn, er: dato- og tidsformateringstegn (a, c, d, h, m, n, p, q, s, t, w, y, /, :), numeriske formateringstegn (#, 0, %, E, e, komma, punktum) og strengformateringstegn (@, &, <, >, !).

Du kan også bruge følgende foruddefinerede talformater. Bortset fra "Generelt tal", returnerer alle de foruddefinerede formatkoder tallet som et decimaltal med to decimalpladser.

Hvis du bruger forud-definerede formater, skal navnet på formatet være omgivet af anførselstegn.

### Foruddefinerede formater

Generel værdi: Tal bliver vist som indtastet.

Valuta: Indsætter et dollartegn foran tallet og omgiver negative tal med parenteser.

Fixed: Viser mindst ét ciffer foran decimaltegnet.

Standard: Viser numre med et tusindtalsskilletegn.

Procent: Ganger tallet med 100 og føjer et procenttegn til tallet.

Videnskabeligt: Viser tal i videnskabelige formater (for eksempel 1.00E+03 for 1000).

En format-kode kan deles i tre afdelinger, der adskilles af semikoloner. Den første del definerer formatet for positive værdier, den anden del for negative værdier, og den tredje del for nul. Hvis du kun angiver en format-kode, gælder den alle tal.

Lokalitetsindstillingerne styrer formatering af tal, datoer og valuta i LibreOffice Basic. Du kan vælge indstillingerne i LibreOffice ▸ PræferencerFunktioner ▸ Indstillinger ▸ Sprog og lokalitetsindstillinger ▸ Generelt. I Basic formatkoder bruges altid punktum (.) som pladsholder for decimaltegnet fra dine lokalitetsindstillinger. Punktum bliver erstattet med det aktuelle decimaltegn.

Det samme gælder lokalitetsindstillingerne for dato-, klokkeslæt- og valutaformater. Basic-formatkode vil blive fortolket og vist ifølge dine lokalitetsindstillinger.

### Eksempel:

        txt = bas.Format(6328.2, '##.##0.00')
        print(txt)

## GetDefaultContext

Returnerer processen tjeneste-fabriks standard-kontekst, hvis den eksisterer, ellers returnerer den en nul-reference.

GetDefaultContext er et alternativ til metoden getComponentContext(), der er tilgængelig fra den globale variabel XSCRIPTCONTEXT eller fra modulet uno.py.

### Syntaks:

svc.GetDefaultContext(): uno

### Returværdi:

Komponentens standardkontekst bruges under instantiering af tjenester via XMultiServiceFactory. Se kapitlet Professional UNO i Udviklerens guide til api.libreoffice.org for at få mere at vide.

### Eksempel:

        ctx = bas.GetDefaultContext()

## GetGuiType

Returnerer en numerisk værdi, der angiver den grafiske brugerflade. Denne funktion leveres kun af hensyn til bagudkompatibilitet med tidligere versioner.

Se metoden system()i Python-modulet platform for at identificere operativsystemet.

### Syntaks:

svc.GetGuiType(): int

### Eksempel:

        n = bas.GetGuiType()

## GetPathSeparator

Returnerer det operativsystem-afhængige skilletegn, der bruges til at angive stier.

Brug os.pathsep i Python-modulet os til at identificere sti-skilletegnet.

### Syntaks:

svc.GetPathSeparator(): str

### Eksempel:

        sep = bas.GetPathSeparator()

## GetSystemTicks

Returnerer antallet tidsenheder, leveret afoperativsystemet. Du kan bruge denne funktion til at optimere visse processer. Brug denne metode til at skønne tid i millisekunder:

### Syntaks:

svc.GetSystemTicks(): int

### Eksempel:

        ticks_ini = bas.GetSystemTicks()
        time.sleep(1)
        ticks_end = bas.GetSystemTicks()
        bas.MsgBox("{} - {} = {}".format(ticks_end, ticks_ini,ticks_end - ticks_ini))

## GlobalScope.BasicLibraries

Returnerer det UNO-objekt, der indeholder alle delte Basic-biblioteker og -moduler.

Denne metode er Pythons svar på GlobalScope.BasicLibraries i Basic-scripts.

### Syntaks:

svc.GlobalScope.BasicLibraries(): uno

### Returværdi:

com.sun.star.script.XLibraryContainer

### Eksempel:

Det følgende eksempel indlæster Basic-biblioteket Gimmicks, hvis det endnu ikke indlæst.

        libs = bas.GlobalScope.BasicLibraries()
        if not libs.isLibraryLoaded("Gimmicks"):
            libs.loadLibrary("Gimmicks")

## GlobalScope.DialogLibraries

Returnerer det UNO-objekt, der indeholder alle delte dialog-biblioteker.

Denne metode er Pythons svar på GlobalScope.DialogLibraries i Basic-scripts.

### Syntaks:

svc.GlobalScope.DialogLibraries(): uno

### Returværdi:

com.sun.star.comp.sfx2.DialogLibraryContainer

### Eksempel:

Det følgende eksempel viser et beskedfelt med navnene på alle tilgængelige dialog-biblioteker.

        dlg_libs = bas.GlobalScope.DialogLibraries()
        lib_names = dlg_libs.getElementNames()
        bas.MsgBox("\n".join(lib_names))

## InputBox

### Syntaks:

svc.InputBox(prompt: str, [title: str], [default: str], [xpostwips: int, ypostwips: int]): str

### Parametre:

prompt: Strengudtryk, der vises som besked i dialogfeltet.

title: Strengudtryk, vist i dialogfeltets titelbjælke.

standard: Strengudtryk, vist som standard i tekstfeltet, hvis der ikke er angivet et andet input.

xpostwips: Heltalsudtryk, der angiver dialogens vandrette placering. Placeringen er en absolut koordinat og henviser ikke til LibreOffices vindue.

ypostwips: Heltaludtryk, der angiver dialogens lodrette placering. Placeringen er en absolut koordinat og henviser ikke til LibreOffices vindue.

Hvis xpostwips og ypostwips udelades, centreres dialogen på skærmen. Position angives i twips.

### Returværdi:

String

### Eksempel:

        txt = s.Indtastningsfelt('Skriv venligst et udtryk:', "Kære bruger")
        s.MsgBox(txt, s.MB_ICONINFORMATION, "Bekræftelse af frase")

Se venligst dybtgående information Input/Output til skærmen med Python på Wiki'en.

## MsgBox

Viser et dialogfelt, der indeholder en besked og returnerer en valgfri værdi.
Mb_xx-konstanter hjælper med til at specificere dialogtypen, antallet af typen af knapper, der skal vises, samt ikontypen. Ved at tilføje deres respektive værdier danner de bit-mønstre, der definerer dialogen MsgBoxs udseende.

### Syntaks:

bas.MsgBox(prompt: str, [buttons: int], [title: str])[: int]

### Parametre:

prompt: Strengudtryk vist som en besked i dialogfeltet. Linjeskift kan indsættes med Chr$(13).

title: Strengudtryk vist i dialogens titelbjælke. Hvis udeladt, viser titelbjælken navnet på det respektive program.

knapper: Et vilkårligt heltalsudtryk, der angiver dialogtypen, såvel som antallet og knaptypen, der skal vises, og deres ikontype.knapper repræsenterer en kombination af bitmønstre, det vil sige: en kombination af elementer kan defineres ved at lægge deres respektive værdier sammen:

### Returværdi:

Et valgfrit heltal som forklaret i IDxx-egenskaber ovenfor.

### Eksempel:

        txt = s.Indtastningsfelt('Skriv venligst et udtryk:', "Kære bruger")
        s.MsgBox(txt, s.MB_ICONINFORMATION, "Bekræftelse af frase")

Se venligst dybtgående information Input/Output til skærmen med Python på Wiki'en.

## Now

Returnerer den aktuelle system-dato og -klokkeslæt som en standard datetime.datetime Python-objekt.

### Syntaks:

svc.Now(): datetime

### Eksempel:

        bas.MsgBox(bas.Now(), bas.MB_OK, "Now")

## RGB

Returnere en heltalsværdi, bestående af røde, grønne og blå komponenter.

### Syntaks:

svc.RGB(red:int, green: int, blue: int): int

### Parametre:

rød: Et vilkårligt heltalsudtryk, der repræsenterer en den røde komponent (0-255) i den sammensatte farve.

grøn: Et vilkårligt heltalsudtryk, der repræsenterer den grønne komponent (0-255) i den sammensatte farve.

blå: Ethvert heltalsudtryk, der repræsenterer den blå komponent (0-255) i den sammensatte farve.

Den resulterende Long værdi beregnes med følgende formel:
Result = red×65536 + green×256 + blue.

I VBA-kompatibilitetstistand (Option VBASupport 1), beregnes Long værdien som
Result = red + green×256 + blue×65536
Se RGB (funktion) [VBA]

Dialogen Farvevælger hjælper med at beregne røde, grønne og blå komponenter i en sammensat farve. Ændring af tekstfarve og Tilpas farve viser dialogen Farvevælger.

### Returværdi:

Integer

### Eksempel:

        YELLOW = bas.RGB(255,255,0)

## Xray

Inspicerer UNO-objekter eller -variable.

### Syntaks:

svc.Xray(obj: any)

### Parametre:

obj: En variabel eller et UNO-objekt.

### Eksempel:

        bas.Xray(bas.StarDesktop)

Alle ScriptForge Basic-rutiner eller identifikatorer, der indledes med et understregstegn "_" er reserveret til internt brug. Det er ikke meningen, at de skal bruges i Basic-makroer eller Python-scripts.

Relaterede emner

GlobalScope-specikation

Programmering med Python-scripts

uno.fileUrlToSystemPath()

uno.systemPathToFileUrl()

Input/Output til skærmen med Python på wiki'en

XSCRIPTCONTEXT.getComponentContext()

uno.getComponentContext()

platform.system()

os.pathsep()