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.

note

Denne tjeneste er tilgængelig fra LibreOffice 7.2 og fremefter.


Typisk eksempel:


   svc.MsgBox('Dette skal vises i et beskedfelt')
  
warning

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
    svc = CreateScriptService("Basic")
  

Egenskaber

Navn

Skrivebeskyttet

Type

Beskrivelse

MB_OK, MB_OKCANCEL, MB_RETRYCANCEL, MB_YESNO, MB_YESNOCANCEL

Ja

heltal

Værdier: 0, 1, 5, 4, 3

MB_ICONEXCLAMATION, MB_ICONINFORMATION, MB_ICONQUESTION, MB_ICONSTOP

Ja

heltal

Værdier: 48, 64, 32, 16

MB_ABORTRETRYIGNORE, MB_DEFBUTTON1, MB_DEFBUTTON2, MB_DEFBUTTON3

Ja

heltal

Værdier: 2, 128, 256, 512

IDABORT, IDCANCEL, IDIGNORE, IDNO, IDOK, IDRETRY, IDYES

Ja

heltal

Værdier: 3, 2, 5, 7, 1, 4, 6
Konstanter, der peger pĂĄ den valgte knap i MsgBox.

StarDesktop

Ja

UNO
objekt

StarDesktop object represents LibreOffice Start Center.


Liste over metoder i tjenesten Basic

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 et numerisk udtryk eller en streng til et standard datetime.datetime Python-objekt.

note

This method exposes the Basic builtin function CDate to Python scripts.


Syntaks:

svc.CDate(expression: any): obj

Parametre:

expression: a numeric expression or a string representing a date.

Når du konverterer et streng-udtryk, skal dato og klokkeslæt indtastes enten i et af de accepterede dato-mønstre, der er defineret til din lokaliseringsindstilling (se ▸ Sprogindstillinger ▸ Sprog) eller i ISO datoformat (for tiden accepteres udelukkende ISO-formatet med bindestreger som "2012-12-31"). I numeriske udtryk, repræsenterer værdier til venstre for decimaltegnet datoen, begyndende fra 311. december 1899. Værdier til højre for decimaltegnet repæsenterer klokkeslættet.

Eksempel:


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

CDateFromUnoDateTime

Converts a UNO date/time representation to a datetime.datetime Python native object.

Syntaks:

svc.CDateFromUnoDateTime(unodate: uno): obj

Parametre:

unodate: A UNO date/time object of one of the following types: com.sun.star.util.DateTime, com.sun.star.util.Date or com.sun.star.util.Time

Eksempel:

The following example creates a com.sun.star.util.DateTime object and converts it to a datetime.datetime Python object.


    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 = svc.CDateFromUnoDateTime(uno_date)
    svc.MsgBox(str(new_date)) # 1983-02-23 00:00:00
  

CDateToUnoDateTime

Converts a date representation into a com.sun.star.util.DateTime object.

Syntaks:

svc.CDateToUnoDateTime(date: obj): uno

Parametre:

date: A Python date/time object of one of the following types: datetime.datetime, datetime.date, datetime.time, float (time.time) or time.struct_time.

Eksempel:


    from datetime import datetime
    current_datetime = datetime.now()
    uno_date = svc.CDateToUnoDateTime(current_datetime)
    svc.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 = svc.ConvertFromUrl( "file:///C:/Program%20Files%20(x86)/LibreOffice/News.txt")
    svc.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 = svc.ConvertToUrl( 'C:\Program Files(x86)\LibreOffice\News.txt')
    svc.MsgBox(url)
  

CreateUnoService

Instantierer en UNO-tjeneste med ProcessServiceManager.

Syntaks:

svc.CreateUnoService(servicename: str): uno

Parametre:

tjenestenavn: Et fuldt kvalificeret tjenestenavn som fx "com.sun.star.ui.dialogs.FilePicker" eller 'com.sun.star.sheet.FunctionAccess'.

Eksempel:


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

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

ĂĄĂĄĂĄĂĄ

Ă…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, værdien interval vil blive tilføjet et antal gange til denne dato/klokkeslæt-værdi.

Returværdi:

En datetime.datetime-værdi.

Eksempel:


    dt = datetime.datetime(2004, 1, 31)
    dt = svc.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 beskrevet i metoden DateAdd ovenfor.

dato1, dato2: 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 = svc.DateDiff('d', date1, date2)
    print(diffDays)
  

DatePart

Datodelen af funktionen 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 ovenfor i metoden DateAdd.

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(svc.DatePart("ww", datetime.datetime(2005,12,31)
    print(svc.DatePart('q', datetime.datetime(1999,12,30)
  

DateValue

Beregner en datoværdi fra en datostreng.

Syntaks:

svc.DateValue(date: str): datetime

Parametre:

Dato: Strengudtryk, der indeholder den dato, du vil beregne. I modsætning til funktionen DatoSerie, der giver år, måneder og dage som særskilte værdier, kræver funktionen DatoVærdi, at datostrengen er i overensstemmelse med et af de dato-acceptmønstre, der er defineret til din lokalisering (se ▸ Sprogindstillinger ▸ Sprog) eller ISO-datoformatet (for tiden kun ISO-datoformat med bindestreger, det vil sige at kun "2012-12-31" accepteres).

Returværdi:

Den beregnede dato.

Eksempel:


    dt = svc.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.

Du kan vælge den lokalitetsindstilling, der styrer formateringen af tal, datoer og valutaer i LibreOffice Basic i - Sprogindstillinger - Sprog. I Basic-formatkoder bliver punktummet (.) altid brugt som pladsholder for decimalseparatoren, der er defineret i din lokalitet og vil blive erstattet med det tilsvarende tegn.

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 = svc.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 = svc.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 = svc.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


    svc.GetPathSeparator(): str
  

Eksempel:


    sep = svc.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 = svc.GetSystemTicks()
    time.sleep(1)
    ticks_end = svc.GetSystemTicks()
    svc.MsgBox("{} - {} = {}".format(ticks_end, ticks_ini,ticks_end - ticks_ini))
  

GlobalScope.BasicLibraries

Returns the UNO object containing all shared Basic libraries and modules.

This method is the Python equivalent to GlobalScope.BasicLibraries in Basic scripts.

Syntaks:

svc.GlobalScope.BasicLibraries(): uno

Returværdi:

com.sun.star.script.XLibraryContainer

Eksempel:

The following example loads the Gimmicks Basic library if it has not been loaded yet.


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

GlobalScope.DialogLibraries

Returns the UNO object containing all shared dialog libraries.

This method is the Python equivalent to GlobalScope.DialogLibraries in Basic scripts.

Syntaks:

svc.GlobalScope.DialogLibraries(): uno

Returværdi:

com.sun.star.comp.sfx2.DialogLibraryContainer

Eksempel:

The following example shows a message box with the names of all available dialog libraries.


    dlg_libs = svc.GlobalScope.DialogLibraries()
    lib_names = dlg_libs.getElementNames()
    svc.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: Integer expression that specifies the horizontal position of the dialog. The position is an absolute coordinate and does not refer to the window of LibreOffice.

ypostwips: Integer expression that specifies the vertical position of the dialog. The position is an absolute coordinate and does not refer to the window of LibreOffice.

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

Returværdi:

streng

Eksempel:


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

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:

svc.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, MB_ICONINFORMATION, "Bekræftelse af udtryk")
  
note

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


Now

Returns the current system date and time as a datetime.datetime Python native object.

Syntaks:

svc.Now(): datetime

Eksempel:


    svc.MsgBox(svc.Now(), svc.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.

tip

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:

heltal

Eksempel:


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

ThisComponent

If the current component refers to a LibreOffice document, this method returns the UNO object representing the document.

The method will return None when the current component does not correspond to a document.

Syntaks:

svc.ThisComponent(): uno

Eksempel:


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

ThisDatabaseDocument

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 method returns None otherwise.

Syntaks:

svc.ThisDatabaseDocument(): uno

Eksempel:


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

Visit the OfficeDatabaseDocument API page to learn more about Base's main component structure.


Xray

Inspicerer UNO-objekter eller -variabler

Syntaks:

svc.Xray(obj: any)

Parametre:

obj: En variabel eller Uno-objekt.

Eksempel:


    svc.Xray(svc.StarDesktop)
  
warning

Alle ScriptForge Basic-rutiner eller identifikatorer, som indledes med et understregningstegn "_" er reserveret til internt brug. De er ikke beregnet til brug i Basic-makroer.


Støt os venligst!