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')
  
warning

Tenesta ScriptForge.Basic er avgrensa til Python-skript.


Oppkall av tenester

note

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

Objektet StarDesktop representerer LibreOffice Startsenter.


Liste over metodar i tenesta Base

CDate
CDateFromUnoDateTime
CDateToUnoDateTime
ConvertFromUrl
ConvertToUrl
CreateUnoService
DateAdd
DateDiff
DatePart

DateValue
Format
GetDefaultContext
GetGuiType
GetPathSeparator
GetSystemTicks
GlobalScope.BasicLibraries
GlobalScope.DialogLibraries
InputBox

MsgBox
Now
RGB
ThisComponent
ThisDatabaseDocument
Xray




CDate

Konverterer eit numerisk uttrykk eller ein streng til eit standard datetime.datetime Python-objekt.

note

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åkinnstillingar → Språk) 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.


    import uno
    uno_date = uno.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))
  

ConvertFromUrl

Returnerer eit filnamn for systembanen for den gjevne file: URL.

Syntaks:

svc.ConvertFromUrl(url: str): str

Parametrar:

url: Ei absolutt file: URL.

Returverdi:

Eit filnamn for systembane.

Eksempel:


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

ConvertToUrl

Returnerer ei file: URL for den gjevne systemstien.

Syntaks:

svc.ConvertToUrl(systempath: str): str

Parametrar:

systemsti: Namnet på ei systemfil som ein streng.

Returverdi:

Ein file: URL som ein streng.

Eksempel:


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

CreateUnoService

Startar ei UNO-teneste med ProcessServiceManager.

Syntaks:

svc.CreateUnoService(servicename: str): uno

Parametrar:

servicename: Eit fult kvalifisert tenestenamn som for eksempel com.sun.star.ui.dialogs.FilePicker eller com.sun.star.sheet.FunctionAccess.

Eksempel:


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

DateAdd

Legg til eit dato- eller klokkeslett-intervall i eit gjeve dato/klokkeslett eit bestemt tal gonger og returnerer den nye datoen.

Syntaks:

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

Parametrar:

intervall: Eit strenguttrykk frå den følgjande tabellen som inneheld 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.

note

The string passed to DateValue must be expressed in one of the date formats defined by your locale setting (see - Language Settings - Languages) or using the ISO date format "yyyy-mm-dd" (year, month and day separated by hyphens).


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åkinnstillingar → Språk. 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")
  
note

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")
  
note

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.

The resulting Long value is calculated with the following formula:
Result = red×65536 + green×256 + blue.

warning

Under VBA compatibility mode (Option VBASupport 1), the Long value is calculated as
Result = red + green×256 + blue×65536
See RGB Function [VBA]


tip

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)
  

ThisComponent

Viss den gjeldande komponenten refererer til eit LibreOffice-dokument, returnerer denne metoden det UNO-objektet som representerer dokumentet.

Metoden returnerer None (ingen) når den gjeldande komponenten ikkje svarar til eit dokument.

Syntaks:

svc.ThisComponent(): uno

Eksempel:


    comp = bas.ThisComponent
    bas.MsgBox("\n".join(comp.getSupportedServiceNames()))
  

ThisDatabaseDocument

Viss skriptet vert køyrd frå eit Base-dokument eller ein av underkomponentane i dokumentet, vil denne metoden returnera hovudkomponenten i Base-eksemplaret.

Denne metoden returnerer elles None (ingen).

Syntaks:

svc.ThisDatabaseDocument(): uno

Eksempel:


    db_doc = bas.ThisDatabaseDocument
    table_names = db_doc.DataSource.getTables().getElementNames()
    bas.MsgBox("\n".join(table_names))
  
tip

Sjå API-sida OfficeDatabasedokument for å læra meir om hovudkomponentstrukturen i Base.


Xray

Inspiserer UNO-objekt eller -variablar

Syntaks:

svc.Xray(obj: any)

Parametrar:

obj: Ein variabel eller eit Uno-objekt.

Eksempel:


    bas.Xray(bas.StarDesktop)
  
warning

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


Støtt oss!