Tenesta ScriptForge.Basic

Tenesta ScriptForge.Basic tilbyr ei samling av LibreOffice Basic-metodar som kan køyrast i ein Python-samanheng. Tenesta Basic sine metodar reproduserer dei innebygde Basic-funksjonane nøyaktig i høve til syntaks og oppførsel.

Typisk eksempel:


   bas.MsgBox('Vis denne teksten i ein meldingsboks frå eit Python-skript')

Tenesta ScriptForge.Basic er avgrensa til Python-skript.

Oppkall av tenester

Før du kan bruka tenesta Basic må du importera metoden CreateScriptService() frå modulen scriptforge:


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

Eigenskapar

Namn	Skriveverna	Type	Skildring
MB_OK, MB_OKCANCEL, MB_RETRYCANCEL, MB_YESNO, MB_YESNOCANCEL	Ja	Integer	Verdiar: 0, 1, 5, 4, 3
MB_ICONEXCLAMATION, MB_ICONINFORMATION, MB_ICONQUESTION, MB_ICONSTOP	Ja	Integer	Verdiar: 48, 64, 32, 16
MB_ABORTRETRYIGNORE, MB_DEFBUTTON1, MB_DEFBUTTON2, MB_DEFBUTTON3	Ja	Integer	Verdiar: 2, 128, 256, 512
IDABORT, IDCANCEL, IDIGNORE, IDNO, IDOK, IDRETRY, IDYES	Ja	Integer	Verdiar: 3, 2, 5, 7, 1, 4, 6 Konstantar som peikar på den valde knappen i MsgBox.
StarDesktop	Ja	UNO- objekt	Returnerer StarDesktop-objektet som representerer LibreOffice-programmet.
ThisComponent	Ja	UNO objekt	Viss den gjeldande komponenten refererer til eit LibreOffice-dokument, returnerer denne metoden UNO-objektet som representerer dokumentet. Denne eigenskapen returnerer Ingen når den gjeldande komponenten ikkje samsvarar med eit dokument.
ThisDatabaseDocument	Ja	UNO objekt	→iss skriptet vert køyrd frå eit Base-dokument eller nokre av underkomponentane i det, returnerer denne metoden hovudkomponenten til Base-førekomsten. Denne eigenskapen returnerer ellesIngen.

Liste over metodar i tenesta Base
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 eit numerisk uttrykk eller ein streng til eit standard datetime.datetime Python-objekt.

Denne metoden viser den innebygde Basic-funksjonen CDate for Python-skript.

Syntaks:

svc.CDate(expression: any): obj

Parametrar:

uttrykk: eit numerisk uttrykk eller ein streng som representerer ein dato.

Når du konverterer eit strenguttrykk, må dato og klokkeslett skrivast inn anten i eitt av dei formata som er definert for språket du brukar (sjå → Språk og nasjonale innstillingar → Generelt) eller i eit ISO datoformat (for tida er berre ISO-formatet med doble hermeteikn gyldig, for eksempel "2012-12-31"). I taluttrykk representerer verdiane til venstre for desimalteiknet datoen med start frå 31. desember 1899. Verdiane til høgre for desimalteiknet representerer klokkeslettet.

Eksempel:


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

CDateFromUnoDateTime

Konverterer ein UNO dato/klokkeslett-representasjon til eit vanleg datetime.datetime Python-objekt.

Syntaks:

svc.CDateFromUnoDateTime(unodate: uno): obj

Parametrar:

unodato: Eit UNO dato/klokkeslett-objekt av desse typane: com.sun.star.util.DateTime, com.sun.star.util.Date eller com.sun.star.util.Time

Eksempel:

Det neste eksempelet lagar eit com.sun.star.util.DateTime-objekt og konverterer det til eit 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 ein dato-representasjon til eit com.sun.star.util.DateTime-objekt.

Syntaks:

svc.CDateToUnoDateTime(date: obj): uno

Parametrar:

dato: Eit Python dato/klokkeslett-objekt av ein av dei følgjande typane: 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))

Parametrar:

intervall: Eit strenguttrykk frå tabellen nedanfor som spesifiserer dato- eller tidsintervallet.

interval (strengverdi)	Forklaring
yyyy	År
q	Kvarter
m	Månad
y	Dagen i året
w	Vekedag
ww	Veke i året
d	Dag
h	Time
n	Minutt
s	Sekund

number: Eit numerisk uttrykk som bestemmer kor ofte verdien av intervall skal leggjast til når han er positiv eller trekkjast frå når han er negativ.

date: Ein gjeven datetime.datetime-verdi, interval-verdien vert lagt til number gongar til denne datetime.datetime-verdien.

Returverdi:

Ein datetime.datetime-verdi.

Eksempel:


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

DateDiff

Returnerer talet på dato- eller klokkeslett-intervall mellom to gjevne dato-/klokkeslett-verdiar.

Syntaks:

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

Parametrar:

interval: Eit strengudtrykk som spesifiserer datointervallet, forklart i metoden DateAdd ovanfor.

date1, date2: Dei to datetime.datetime-verdiane som skal samanliknast.

firstdayofweek ‒ Ein valfri parameter som bestemmer første dagen i veka.

firstdayofweek-verdi	Forklaring
0	Bruk standardverdien frå systemet
1	Søndag (standard)
2	Måndag
3	Tysdag
4	Onsdag
5	Torsdag
6	Fredag
7	Laurdag

firstweekofyear ‒ Ein valfri parameter som bestemmer den første veka i eit år.

firstweekofyear-verdi	Forklaring
0	Bruk standardverdien frå systemet
1	Veke 1 er den veka som inneheld 1. januar 8standard)
2	Veke 1 er den første veka dette året som inneheld fire eller fleire dagar
3	Veke 1 er den første veka som inneheld dagar berre frå det nye året

Returverdi:

Eit tal

Eksempel:


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

DatePart

Funksjonen DatePart returnerer ein spesifisert del av ein dato.

Syntaks:

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

Parametrar:

interval: Eit strengudtrykk som spesifiserer datointervallet, vist i metoden DateAdd ovanfor.

dato: Datoen/klokkeslettet som resultatet skal reknast ut for.

førstedagiveka, førstevekeiåret: valfrie parameterar som spesifiserer den første dagen i veka og den første veka i året ut frå forklaringa ovanfor i metoden DateDiff.

Returverdi:

Den uttrukne delen av ein gjeven dato/eit gjeve klokkeslett.

Eksempel:


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

DateValue

Reknar ut ein datoverdi frå ein datostreng.

Syntaks:

svc.DateValue(date: str): datetime

Parametrar:

dato: Ein streng som inneheld datoen som vert konvertert til eit Dato-objekt.

Strengen som vert sendt til DateValue må vera i eit av datoformata som er definert av lokalinnstillinga di (sjå → Språk og nasjonale innstillingar → Generelt) eller bruk ISO-datoformatet «åååå-mm-dd» (år, månad og dag skild med bindestrekar).

Returverdi:

Den utrekna datoen.

Eksempel:


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

Format

Konverterer eit tal til ein streng og formaterer det i høve til det gjevne formatet.

Syntaks:

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

Parametrar:

uttrykk: Taluttrykket som skal konverterast til ein formatert streng.

format: Streng med formatkoden for talet. Viss format er sløyfa, verkar format-funksjonen på same måten som LibreOffice Basic-funksjonen Str().

Returverdi:

Tekststreng.

Formateringskodar

Lista nedanfor viser kodane som kan nyttast for å formatera eit taluttrykk:

0: Viss uttrykk har eit siffer der 0 er plassert i formatkoden, vert sifferet vist, elles vert det vis ein 0.

Viss uttrykk har færre siffer enn talet på nullar i formatkoden, (på begge sider av desimalteiknet), vert leiande eller avsluttande nullar viste. Viss uttrykk har fleire siffer til venstre for desimalteiknet enn formatkoden har, vert dei overskytande sifra viste utan formatering.

Desimalplassar i uttrykkt vert avrunda i høve til talet på nullar som kjem etter desimalteiknet i Format-koden.

#: Viss uttrykk har eit siffer der #-plasshaldaren er plassert i formatkoden, vert sifferet vist, elles ingenting.

Dette symbolet verkar på same måten som 0, utanom at leiande og avsluttande nullar ikkje vert viste viss det er fleire #-teikn i formatkoden enn siffer i uttrykk. Berre dei relevante sifra i uttrykk vert viste.

.: Plasshaldaren for desimalteiknet bestemmer talet på desimalplassar til høgre og venstre for desimalteiknet.

Viss formatkode inneheld berre #-plasshaldarar til venstre for dette symbolet, vil tal mindre enn 1 byrja med desimalteiknet. For alltid å visa ein leiande null ved desimaltal, bruk 0 som plasshaldar på den første plassen framføre desimalteiknet.

%: Multipliserer uttrykk med 100 og set inn prosentteiknet (%) der uttrykk er i format-koden.

E- E+ e- e+ : Viss format-koden inneheld minst ein plasshaldar for siffer (0 eller #) til høgre for symbolet E-, E+, e- eller e+, vert uttrykk formatert vitskapleg i eksponentialform. Bokstaven E eller e vert set inn mellom talet og eksponenten. Talet på plasshaldarar for tal til høgre for symbolet bestemmer talet på siffer i eksponenten.

Viss eksponenten er negativ, vert eit minusteikn (-) vist direkte framføre eksponenten med E-, E+, e-, e+. Viss eksponenten er positiv, vert plussteiknet vist berre framføre eksponentar med E+ eller e+.

Tusenskiljeteiknet vert vist viss format-koden inneheld skiljeteiknet omgjeve av plasshaldarar for tal (0 eller #).

Bruk av punktum som tusenskilje eller desimalteikn er avhengig av dei lokale innstillingane. Når du skriv inn eit tal direkte i BASIC kjeldekode, må du bruka punktum som desimalskiljeteikn. Kva teikn som vert vist som desimalteikn er derimot avhengig av talformatet sett i systeminnstillingane.

- + $ ( ) mellomrom: A pluss (+), minus (-), dollar ($), mellomrom, eller parentesar skrivne direkte i format-koden, vert viste som bokstavteikn.

For å kunna visa andre teikn enn dei som er lista her, må du setja ein bakoverstrek (\) framføre dei eller setja dei i doble hermeteikn (" ").

\ : Bakoverstreken viser det neste teiknet i format-koden.

Teikn i format-koden med ei spesiell meining kan berre visast som bokstavteikn viss dei har ein bakoverstrek framføre seg. Bakoverstreken vert ikkje vist. For å visa bakoverstrek må du skriva ein bakoverstrek framføre i formatkoden (\\).

Teikna som må ha ein bakoverstrek framføre seg for å verta viste som bokstavteikn, er formateringsteikna for dato og klokkeslett (a, c, d, h, m, n, p, q, s, t, w, y, /, :), numeriske formateringsteikn (#, 0, %, E, e, komma, punktum) og strengformateringsteikna (@, &, <, >, !).

Du kan også bruka følgjande førehandsdefinerte talformat. Med unnatak av "Generelle tal" returnerer alle dei førehandsdefinerte formatkodane talet som eit desimaltal med to desimalar.

Viss du brukar førehandsdefinerte format, må namnet på formatet skrivast mellom doble hermeteikn ("").

Førehandsdefinerte format

Generelle tal: Tala vert viste slik dei er skrivne inn.

Valuta: Set inn eit dollarteikn framføre talet og set negative tal i parentes.

Fixed: Viser minst eitt tal framføre desimalteiknet.

Standard: Viser talet med tusenskiljeteikn.

Prosent: Multipliserer talet med 100 og legg til prosentteiknet.

Vitskapleg: Viser talet i vitskapleg notasjon (for eksempel 1.00E+03 for 1000).

Ein format-kode kan delast i tre delar skilde med semikolon. Den første delen definerer formatet på ein positiv verdi, den andre for negative verdiar og den tredje for null. Set du opp berre éin format-kode, vil denne gjelda for alle tal.

Dei lokale innstillingane som styrer formateringa av tal, datoar og valuta i LibreOffice Basic vert sette i → Språk og nasjonale innstillingar → Generelt. I Basic-formatkodar vert alltid punktum (.) brukt som plasshaldar for desimalskiljeteiknet som er definert lokalt. Punktumet vert erstatta med det aktuelle skiljeteiknet.

Det same gjeld for dei lokale innstillingane for dato-, tid- og valuta-format. Basic-formatet vil verta tolka og vist i høve til dei lokale språkinnstillingane.

Eksempel:


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

GetDefaultContext

Returnerer standardsamanhengen for prosesstenestefabrikken viss denne finst, elles ein nullreferanse.

GetDefaultContext er eit alternativ til metoden getComponentContext() som er tilgjengeleg frå den globale variabelen XSCRIPTCONTEXT eller frå modulen uno.py.

Syntaks:

svc.GetDefaultContext(): uno

Returverdi:

Standard komponentkontekst vert brukt ved instansiering av tenester via XMultiServiceFactory. Sjå kapittelet Professional UNO i Utviklarens guide til api.libreoffice.org for meir informasjon.

Eksempel:


    ctx = bas.GetDefaultContext()

GetGuiType

Returnerer ein numerisk verdi som gjev den grafiske brukarflata. Denne funksjonen er berre tatt med for å vera bakoverkompatibel med tidlegare versionar.

Sjå metoden system()i Python-modulen platform for å identifisere operativsystemet.

Syntaks:

svc.GetGuiType(): int

Eksempel:


    n = bas.GetGuiType()

GetPathSeparator

Returnerer teiknet som vert brukt av operativsystemet for å skilja mapper i filstiane.

Bruk os.pathsep i Python-modulen os til å identifisere sti-skiljeteiknet.

Syntaks:

svc.GetPathSeparator(): str

Eksempel:


    sep = bas.GetPathSeparator()

GetSystemTicks

Returnerer talet på «system-ticks». Denne funksjonen kan brukast for å optimalisera ulike prosessar. Bruk denne metoden for å estimere 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-objektet som inneheld alle delte Basic-bibliotek og -modular.

Denne metoden er Python sitt svar på GlobalScope.BasicLibraries i Basic-skript.

Syntaks:

svc.GlobalScope.BasicLibraries(): uno

Returverdi:

com.sun.star.script.XLibraryContainer

Eksempel:

Det neste eksempelet lastar inn Basic-biblioteket Gimmicks, viss dette ikkje alt er gjort.


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

GlobalScope.DialogLibraries

Returnerer det UNO-objektet som inneheld alle delte dialog-bibliotek.

Denne metoden er Python sitt svar på GlobalScope.BasicLibraries i Basic-skript.

Syntaks:

svc.GlobalScope.DialogLibraries(): uno

Returverdi:

com.sun.star.comp.sfx2.DialogLibraryContainer

Eksempel:

Det neste eksempelet viser eit meldingsfelt med namna på alle tilgjengelege dialog-bibliotek.


    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

Parametrar:

prompt: Strenguttrykket som vert vist som melding i dialogvindauget.

Title: Strenguttrykket som vert vist i tittelfeltet for dialogvindauget.

default: Strenguttrykket som vert vist i tekstfeltet i dialogvindauget viss det ikkje er skrive inn inndata.

xpostwips: Heiltalsuttrykk som bestemmer den vassrette plasseringa av dialogvindauget. Plasseringa er ein absolutt koordinat og har ingen ting med LibreOffice-vindauget å gjera.

ypostwips: Heiltalsuttrykk som bestemmer den loddrette plasseringa av dialogvindauget. Plasseringa er ein absolutt koordinat og har ingen ting med LibreOffice-vindauget å gjera.

Viss xpostwips og ypostwips er sløyfa, vert dialogvindauget midtstilt på skjermen. Plasseringa vert bestemt med måleeininga twips.

Returverdi:

String

Eksempel:


    txt = s.InputBox ('Skriv inn eit uttrykk:','Kjære brukar')
    s.MsgBox(txt, s.MB_ICONINFORMATION, "Stadfesting av frase")

Sjå djuptgåande informasjon på Inndata/utdata til skjermen med Python på Wiki'en.

MsgBox

Viser eit dialogvindauge som inneheld ei melding og returnerer ein valfri verdi.
MB_xx-konstanter hjelper til å spesifisere type dialogvindauge, talet på knappetypar som skal visast og ikontypen. Når du legg inn dei respektive verdiane, lagar desse eit bit-mønstre som definerer utsjånaden på dialogvindauget MsgBox.

Syntaks:

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

Parametrar:

prompt Strenguttrykk som vert vist som ei melding i dialogvindauget. Linjeskift kan setjast inn med Chr$(13).

title: Strenguttrykk som vert vist på tittellinja i dialogvindauget. Viss denne vert sløyfa, vert programnamnet vist på tittellinja.

knappar: Eit heiltalsuttrykk som bestemmer dialogvindaugetypen, kor mange og kva type knappar som skal visast og ikontypen. knappar er ein kombinasjon av bit-mønster, det vil seia ein kombinasjon av element som vert definert ved å leggja saman dei respektive verdiane:

Returverdi:

Eit valfritt heiltal som forklart i IDxx-eigenskapane ovanfor.

Eksempel:


    txt = s.InputBox ('Skriv inn eit uttrykk:','Kjære brukar')
    s.MsgBox(txt, s.MB_ICONINFORMATION, "Stadfesting av frase")

Sjå djuptgåande informasjon på Inndata/utdata til skjermen med Python på Wiki'en.

Now

Returnerer den gjeldande system-datoen og -klokkeslettet som datetime.datetime Python-objekt.

Syntaks:

svc.Now(): datetime

Eksempel:


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

RGB

Returnerer ein heiltals fargeverdi sett saman av dei raude, grøne og blå komponentane.

Syntaks:

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

Parametrar:

Red: Kva heiltalsuttrykk som helst som representerer den raude komponenten (0 - 255) i ein samansett farge.

green: Kva heiltalsuttrykk som helst som representerer den grøne komponenten (0 - 255) i ein samansett farge.

blue: Kva heiltalsuttrykk som helst som representerer den blå komponenten (0 - 255) i ein samansett farge.

Den resulterande Lang-verdien vert rekna ut ved å bruka denne formelen:
Resultat = raud×65536 + grøn×256 + blå

I VBA-kompatibilitetsmodus (Option VBASupport 1) vert Long-verdien rekna ut som
Result = raud + grøn×256 + blå×65536
Sjå RGB-funksjonen [VBA]

Dialogvindauget Fargehentar hjelper med å rekna ut raude, grøne og blå komponentar i ein samansett farge. Endra tekstfarge og val av Tilpass farge vil også visa dialogvindauget for fargehentaren.

Returverdi:

Integer

Eksempel:


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

Xray

Inspiserer UNO-objekt eller -variablar

Syntaks:

svc.Xray(obj: any)

Parametrar:

obj: Ein variabel eller eit Uno-objekt.

Eksempel:


    bas.Xray(bas.StarDesktop)

Alle ScriptForge Basic-rutinane og -identifikatorane som vert innleidde med understrek «_» er reserverte for internt bruk. Dei er ikkje meint brukte i Basic-makroar.

GlobalScope-spesifikator

Programmering med Python-skript

uno.fileUrlToSystemPath()

uno.systemPathToFileUrl()

Inndata/utdata til skjermen med Python på wiki-en

XSCRIPTCONTEXT.getComponentContext()

uno.getComponentContext()

platform.system()

os.pathsep()