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	Returns the StarDesktop object that represents the LibreOffice application.
ThisComponent	Yes	UNO object	If the current component refers to a LibreOffice document, this method returns the UNO object representing the document. This property returns None when the current component does not correspond to a document.
ThisDatabaseDocument	Yes	UNO object	If the script is being executed from a Base document or any of its subcomponents this method returns the main component of the Base instance. This property returns None otherwise.

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.

When you convert a string expression, the date and time must be entered either in one of the date acceptance patterns defined for your locale setting (see - Languages and Locales - General) or in ISO date format (momentarily, only the ISO format with hyphens, e.g. "2012-12-31" is accepted). In numeric expressions, values to the left of the decimal represent the date, beginning from December 31, 1899. Values to the right of the decimal represent the time.

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

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.

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

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.

You can set the locale used for controlling the formatting numbers, dates and currencies in LibreOffice Basic in - Languages and Locales - General. In Basic format codes, the decimal point (.) is always used as placeholder for the decimal separator defined in your locale and will be replaced by the corresponding character.

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

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

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 er indledet med et understreget tegn "_" er reserveret til internt brug. Det er ikke meningen, at de skal bruges i Basic-makroer eller Python-scripts.

GlobalScope-specifikator

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