ScriptForge.Basic service

De service ScriptForge.Basic bevat een aantal LibreOffice Basic methoden die vanuit Python uitgevoerd kunnen worden. De methoden in de service Basic gebruiken dezelfde syntaxis en doen hetzelfde als de ingebouwde Basic-functies.

Typerend voorbeeld:


   bas.MsgBox('Toon deze tekst in een berichtvenster vanuit een Python-script')

De service ScriptForge.Basic is alleen voor gebruik in Python-scripts.

Service aanroep

Voordat de service Basic gebruikt kan worden moet de methode CreateScriptService worden geïmporteerd uit de module scriptforge:


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

Eigenschappen

Naam	AlleenLezen	Type	Beschrijving
MB_OK, MB_OKCANCEL, MB_RETRYCANCEL, MB_YESNO, MB_YESNOCANCEL	Ja	Integer	Waarden: 0, 1, 5, 4, 3
MB_ICONEXCLAMATION, MB_ICONINFORMATION, MB_ICONQUESTION, MB_ICONSTOP	Ja	Integer	Waarden: 48, 64, 32, 16
MB_ABORTRETRYIGNORE, MB_DEFBUTTON1, MB_DEFBUTTON2, MB_DEFBUTTON3	Ja	Integer	Waarden: 2, 128, 256, 512
IDABORT, IDCANCEL, IDIGNORE, IDNO, IDOK, IDRETRY, IDYES	Ja	Integer	Waarden: 3, 2, 5, 7, 1, 4, 6 Een constante die aangeeft welke knop in de MsgBox is ingedrukt.
StarDesktop	Ja	UNO -object	Retourneert het StarDesktop-object dat de toepassing LibreOffice vertegenwoordigt.
ThisComponent	Ja	UNO -object	Als de huidige component verwijst naar een LibreOffice-document, retourneert deze methode het UNO-object dat het document vertegenwoordigt. Deze eigenschap retourneert Geen wanneer de huidige component niet overeenkomt met een document.
ThisDatabaseDocument	Ja	UNO -object	Als het script wordt uitgevoerd vanuit een Base-document of een van de subcomponenten ervan, retourneert deze methode de hoofdcomponent van de Base-instantie. Anders retourneert deze eigenschap Geen.

De lijst met methoden in de service 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

Converteert een numerieke expressie of een tekenreeks naar een intern datetime.datetime Python-object.

Met deze methode kan de interne Basic-functie CDate worden gebruikt in Python-scripts.

Syntaxis:

svc.CDate(expression: any): obj

Parameters:

expression: een numerieke expressie of een tekenreeks die staat voor een datum.

Wanneer u een tekenreeksexpressie converteert, moeten de datum en tijd worden ingevoerd in een van de datumacceptatiepatronen die zijn gedefinieerd voor uw landinstelling (zie - Taalinstellingen - Talen) of in ISO datumformaat (momenteel wordt alleen het ISO-formaat met koppeltekens, bijvoorbeeld "31-12-2012" geaccepteerd). In numerieke uitdrukkingen vertegenwoordigen waarden links van de decimaal de datum, beginnend op 31 december 1899. Waarden rechts van de decimaal vertegenwoordigen de tijd.

Voorbeeld:


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

CDateFromUnoDateTime

Converteert een UNO date/time veld naar een intern datetime.datetime Python-object.

Syntaxis:

svc.CDateFromUnoDateTime(unodate: uno): obj

Parameters:

unodate: Een UNO datum/tijd object van een van de volgende types: com.sun.star.util.DateTime, com.sun.star.util.Date of com.sun.star.util.Time

Voorbeeld:

In dit voorbeeld wordt een com.sun.star.util.DateTime object aangemaakt en daarna geconverteerd naar een datetime.datetime Python object.


    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

Converteert een representatie van een datum naar een com.sun.star.util.DateTime object.

Syntaxis:

svc.CDateToUnoDateTime(date: obj): uno

Parameters:

date: Een Python datum/tijd object van een van de volgende types: datetime.datetime, datetime.date, datetime.time, float (time.time) of time.struct_time.

Voorbeeld:


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

Parameters:

interval: Een tekst uit de onderstaande tabel die aangeeft wat het datum/tijd interval is.

interval (Tekst)	Uitleg
yyyy	Jaar
q	Kwartaal
m	Maand
y	Dag van het jaar
w	Dag van de week
ww	Week van het jaar
d	Dag
h	Uur
n	Minuut
s	Seconde

number: Een numerieke expressie die aangeeft hoe vaak de waarde van het interval wordt opgeteld (positieve waarde) of afgetrokken (negatieve waarde).

date: Een datetime.datetime waarde die het beginpunt aangeeft, de waarde van het interval wordt number keer aan deze datetime.datetime waarde toegevoegd.

Geretourneerde waarde:

Een datetime.datetime waarde.

Voorbeeld:


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

DateDiff

Retourneert het aantal dagen of het aantal tijdsintervallen tussen twee opgegeven datums/tijden.

Syntaxis:

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

Parameters:

interval: Een tekenreeks expressie die het datuminterval aangeeft, zoals hierboven bij de methode DateAdd is beschreven.

date1, date2: De twee datetime.datetime waarden die vergeleken gaan worden.

eerstedagvandeweek: Een optionele parameter die de eerste dag van de week aangeeft.

eerstedagvandeweek waarde	Uitleg
0	Standaardwaarde van het systeem gebruiken
1	Zondag (standaard)
2	Maandag
3	Dinsdag
4	Woensdag
5	Donderdag
6	Vrijdag
7	Zaterdag

eersteweekvanhetjaar: Een optionele parameter die de eerste week van het jaar aangeeft.

eersteweekvanhetjaar waarde	Uitleg
0	Standaardwaarde van het systeem gebruiken
1	Week 1 is de week waarin 1 januari valt (standaard)
2	Week 1 is de eerste week waarin vier of meer dagen van dat jaar vallen
3	Week 1 is de eerste week waarin alleen dagen van het nieuwe jaar vallen

Geretourneerde waarde:

Een getal.

Voorbeeld:


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

DatePart

De functie DatePart retourneert een aangegeven deel van een datum.

Syntaxis:

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

Parameters:

interval: Een tekst die het datuminterval aangeeft, dit zoals hierboven bij de methode DateAdd is beschreven.

date: De datum waaruit het resultaat wordt berekend.

firstdayofweek, firstweekofyear: optionele parameters die de eerste dag van de week resp. jaar aangeven. dit zoals hierboven bij de methode DateDiff is beschreven.

Geretourneerde waarde:

Het gevraagde deel uit de gegeven datum/tijd.

Voorbeeld:


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

DateValue

Bepaalt een datumwaarde uit een tekenreeks die een datum weergeeft.

Syntaxis:

svc.DateValue(date: str): datetime

Parameters:

date: een tekenreeks die de datum bevat die wordt geconverteerd naar een Date-object.

De tekenreeks die wordt doorgegeven aan DateValue moet worden uitgedrukt in een van de datumnotaties die zijn gedefinieerd door uw landinstelling (zie - Taalinstellingen - Talen) of gebruik de ISO datumformaat "jjjj-mm-dd" (jaar, maand en dag gescheiden door koppeltekens).

Geretourneerde waarde:

De berekende datum.

Voorbeeld:


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

Format

Converteert een getal naar een tekenreeks en past het aan volgens de gespecificeerde opmaak.

Syntaxis:

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

Parameters:

expression: Numerieke expressie die u wilt omzetten naar een geformatteerde tekenreeks.

format: Tekenreeks die de formaatcode specificeert voor het getal. Indien format wordt weggelaten, dan werkt de functie Format function als de LibreOffice Basic functie Str().

Geretourneerde waarde:

Tekenreeks.

Opmaakcodes

De codes die gebruikt kunnen worden voor het formatteren van een numerieke expressie zijn:

0: Indien de expression een cijfer bevat op de positie van de 0 in de format code, dan wordt het cijfer getoond en anders wordt er een nul getoond.

Als de expression minder cijfers bevat dan het aantal nullen in de format code, (aan beide zijden van de decimaal), dan worden nullen vooraan en achteraan getoond, Als de expression meer cijfers heeft voor de komma dan het aantal nullen in de format code, dan worden die extra cijfers onopgemaakt getoond.

Decimale plaatsen in de expression worden afgerond naar het aantal nullen na het decimale scheidingsteken in de format code.

#: Als de expression een cijfer bevat op de plaats van de # placeholder in de format code, dan wordt op die positie het cijfer getoond en anders niets.

Het symbool werkt als de 0, echter zonder dat de nullen vooraan en achteraan worden getoond als er meer # tekens in de format code voorkomen dan in de expression. Alleen relevante cijfers van de expression worden getoond.

.: Het decimaalteken bepaalt het aantal decimale posities aan de linker- en rechterkant van het decimale scheidingsteken.

Als de format code links van dit symbool alleen # placeholders bevat, dan staat er voor getallen kleiner dan 1 een decimaal scheidingsteken. Om in deze gevallen toch een nul voor het decimaal scheidingsteken te krijgen dient u als placeholder een 0 te gebruiken op de eerste plaats links van het decimaal scheidingsteken.

%: Vermenigvuldigt de expressionmet 100 en voegt het procentteken (%) toe waar de expression voorkomt in de format code.

E- E+ e- e+ : Als de format code minstens een placeholder voor een cijfer (0 or #) bevat rechts van het symbool E-, E+, e-, or e+, dan wordt de expression opgemaakt in de de wetenschappelijke ook wel de exponentiële notatie. De letter E of e komt te staan tussen het getal en de exponent. Het aantal placeholders voor cijfers rechts van het symbool bepaald het aantal cijfers in de exponent.

Als de exponent negatief is, wordt een minteken vlak voor een exponent met E-, E+, e-, e+ geplaatst. Als de exponent positief is wordt een plusteken alleen voor exponenten met E+ of e+ geplaatst.

Het scheidingsteken voor duizendtallen wordt getoond als in de format code het scheidingsteken wordt omgeven door placeholders voor cijfers (0 or #).

Het gebruik van de punt als scheidingsteken voor duizendtallen en decimalen is afhankelijk van de landinstellingen. Als u een getal direct in BASIC-broncode invoert, gebruik dan altijd een punt als decimaal scheidingsteken. Het feitelijke teken dat wordt weergegeven als decimaal scheidingsteken is afhankelijk van uw systeeminstellingen.

- + $ ( ) space: Een plus (+), minus (-), dollar ($), spatie of haakjes in de format code worden getoond als tekst.

Om andere tekens dan die hier opgesomd werden weer te geven, moet u het laten voorafgaan door een backslash (\), of het tussen aanhalingstekens plaatsen (" ").

\ : De backslash geeft aan dat het volgende teken in de format code dat teken zelf is en geen teken met een speciale betekenis voor de opmaak.

Tekens in de format code die een speciale betekenis hebben kunnen dus alleen als tekst worden getoond door er een backslash voor te zetten. De backslash wordt uiteraard niet getoond, om een backslash te tonen dient u een dubbele backslash (\\) in de de opmaakcode te zetten.

Tekens die moeten worden voorafgegaan door een backslash in de opmaakcode om te worden weergegeven als letterlijke tekens zijn de datum- en tijdopmaaktekens (a, c, d, h, m, n, p, q, s, t, w, y, /, :), numerieke opmaaktekens (#, 0, %, E, e, komma, punt) en tekenreeksopmaaktekens (@, &, <, >, !).

U kunt ook een al gedefinieerde opmaak voor getallen gebruiken. Met uitzondering van de "Algemene getalopmaak" tonen al die opmaakcodes het getal als een getal met twee cijfers achter de komma.

Als u voorgedefinieerde opmaak gebruikt, moet de naam van de opmaak tussen aanhalingstekens staan.

Vooraf gedefinieerde opmaak

Getallen: Getallen worden getoond zoals ingevoerd.

Valuta: Er wordt een dollarteken vóór het getal geplaatst en negatieve getallen worden tussen ronde haakjes gezet.

Vast: Tenminste één cijfer wordt getoond vóór het decimale scheidingsteken.

Standaard: Toont getallen met een scheidingsteken voor duizendtallen.

Percent: Het getal wordt vermenigvuldigd met 100 en een procentteken wordt achter het getal geplaatst.

Wetenschappelijk: Toont getallen in wetenschappelijke opmaak (bijv., 1,00E+03 voor 1000).

Een format code kan in drie delen worden verdeeld met puntkomma's. Er dan dan een andere opmaak gegeven worden voor respectievelijk positieve waarde, negatieve waarden en de waarde nul. Als er maar een deel wordt ingevuld in de format code, dan is dat van toepassing op alle getallen.

U kunt de landinstelling instellen die wordt gebruikt voor het beheren van de opmaak van getallen, datums en valuta's in LibreOffice Basic in - Taalinstellingen - Talen. In basisformaatcodes wordt de decimale punt (.) altijd gebruikt als plaatsaanduider voor het decimaalscheidingsteken dat in uw taalinstelling is gedefinieerd en wordt vervangen door het overeenkomstige teken.

Hetzelfde geldt voor de landinstellingen voor datum-, tijd- en valuta-opmaak. De BASIC-notatiecode wordt geïnterpreteerd en weergegeven volgens uw landinstelling.

Voorbeeld:


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

GetDefaultContext

Retourneert de standaardcontext van de processervicefactory, indien aanwezig, anders retourneert een null-referentie.

GetDefaultContext is een alternatief voor de methode getComponentContext die via de globale variabele XSCRIPTCONTEXT of van de module uno.py beschikbaar is.

Syntaxis:

svc.GetDefaultContext(): uno

Geretourneerde waarde:

De standaard component context wordt gebruikt als de services via XMultiServiceFactory worden aangemaakt. Lees het hoofdstuk Professional UNO in de Developer's Guide op api.libreoffice.org voor meer informatie.

Voorbeeld:


    ctx = bas.GetDefaultContext()

GetGuiType

Retourneert een numerieke waarde die de grafische gebruikersinterface aangeeft. Deze functie is alleen bedoeld voor achterwaartse compatibiliteit met eerdere versies.

Refereer aan de methode system van de Python-module platform om het besturingssysteem te bepalen.

Syntaxis:

svc.GetGuiType(): int

Voorbeeld:


    n = bas.GetGuiType()

GetPathSeparator

Retourneert het besturingssysteemafhankelijke mapscheidingsteken dat wordt gebruikt om bestandspaden op te geven.

Gebruik os.pathsep van de Python-module os om het pad scheidingsteken te bepalen.

Syntaxis:

svc.GetPathSeparator(): str

Voorbeeld:


    sep = bas.GetPathSeparator()

GetSystemTicks

Retourneert het aantal systeemticks dat door het besturingssysteem wordt geleverd. U kunt deze functie gebruiken om bepaalde processen te optimaliseren. Gebruik deze methode om de tijd in milliseconden te schatten:

Syntaxis:

svc.GetSystemTicks(): int

Voorbeeld:


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

GlobalScope.BasicLibraries

Retourneert het UNO-object dat alle gedeelde Basic bibliotheken en modules bevat.

De methode is in Python de equivalent van GlobalScope.BasicLibraries in Basic.

Syntaxis:

svc.GlobalScope.BasicLibraries(): uno

Geretourneerde waarde:

com.sun.star.script.XLibraryContainer

Voorbeeld:

In het volgende voorbeeld wordt de Gimmicks Basic-bibliotheek geladen als deze nog niet is geladen.


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

GlobalScope.DialogLibraries

Retourneert het UNO-object dat alle gedeelde dialoogbibliotheken bevat.

Deze methode is in Python de equivalent van GlobalScope.DialogLibraries in Basic.

Syntaxis:

svc.GlobalScope.DialogLibraries(): uno

Geretourneerde waarde:

com.sun.star.comp.sfx2.DialogLibraryContainer

Voorbeeld:

Het volgende voorbeeld toont een berichtvenster met de namen van alle beschikbare dialoogbibliotheken.


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

InputBox

Syntaxis:

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

Parameters:

prompt:Tekst die wordt getoond als het bericht in het dialoogvenster.

titel: Tekst die getoond wordt in de titelbalk van het dialoogvenster.

standaardwaarde: Tekst die in het tekstvak wordt getoond als er geen invoer wordt ingevuld.

xpostwips: Getal die de horizontale positie aangeeft van de dialoog. De positie is een absolute coördinaat en staat los van het venster van LibreOffice.

ypostwips: Getal die de verticale positie aangeeft van de dialoog. De positie is een absolute coördinaat en staat los van het venster van LibreOffice.

Als xpostwips en ypostwips worden weggelaten, dan wordt de dialoog op het scherm gecentreerd. De positie wordt gespecificeerd in twips.

Geretourneerde waarde:

String

Voorbeeld:


    txt = s.InputBox('Vul a.u.b. een korte zin in:', "Beste gebruiker")
    s.MsgBox(txt, s.MB_ICONINFORMATION, "Bevestiging van de korte zin")

Een uitgebreide beschrijving staat op de wiki: Input/Output to Screen with Python.

MsgBox

Toont een dialoogvenster met een bericht en retourneert een optionele waarde.
MB_xx-constanten helpen bij het specificeren van het dialoogtype, het aantal en het type knoppen dat moet worden weergegeven, plus het pictogramtype. Door hun respectieve waarden toe te voegen, vormen ze bitpatronen, die het uiterlijk van het dialoogvenster MsgBox bepalen.

Syntaxis:

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

Parameters:

prompt: De tekst die wordt getoond in het dialoogvenster. Een regeleinde kan worden toegevoegd met Chr$(13).

title: tekenreeks die wordt weergegeven in de titelbalk van het dialoogvenster. Indien weggelaten, wordt daar de naam van de toepassing weergegeven.

buttons: Een geheel getal die het dialoogtype aangeeft, als ook het aantal en type van de te tonen knoppen en het pictogram-type. buttons staat voor een combinatie van patronen van bits, daar mee wordt bedoeld, een combinatie van elementen kan worden gedefinieerd bij optellen van de respectievelijke waarden:

Geretourneerde waarde:

Een optioneel geheel getal zoals beschreven in bovenstaande IDxx-eigenschappen.

Voorbeeld:


    txt = s.InputBox('Vul a.u.b. een korte zin in:', "Beste gebruiker")
    s.MsgBox(txt, s.MB_ICONINFORMATION, "Bevestiging van de korte zin")

Een uitgebreide beschrijving staat op de wiki: Input/Output to Screen with Python.

Now

Retourneert de huidige systeemdatum en -tijd als een datetime.datetime native Python-object.

Syntaxis:

svc.Now(): datetime

Voorbeeld:


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

RGB

Retourneert een gehele kleurwaarde die bestaat uit rode, groene en blauwe componenten.

Syntaxis:

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

Parameters:

rood: Een getal dat de rode component (0-255) aangeeft van de samengestelde kleur.

groen: Een getal dat de groene component (0-255) aangeeft van de samengestelde kleur.

blauw: Een getal dat de blauwe component (0-255) aangeeft van de samengestelde kleur.

Het resultaat heeft een Long waarde en wordt als volgt berekend:
Rood×65536 + Groen×256 + Blauw.

In de VBA-compatibiliteit-mode (Option VBASupport 1) wordt de Long waarde berekend als volgt
Rood + Groen × 256 + Blauw x 65536
Bekijk de Functie RGB [VBA]

De dialoog kleurkiezer helpt het bepalen van de rode, groene en blauwe componenten van een samengestelde kleur. De dialoog wordt gebruikt bij het wijzigen van de kleurtekst en het kiezen van een eigen kleur.

Geretourneerde waarde:

Integer

Voorbeeld:


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

Xray

Uno-objecten of variabelen onderzoeken.

Syntaxis:

svc.Xray(obj: any)

Parameters:

obj: Een variabele of UNO-object.

Voorbeeld:


    bas.Xray(bas.StarDesktop)

Alle ScriptForge Basic-routines of variabelen die beginnen met een underscore "_" zijn voor intern gebruik. Gebruik deze niet in een Basic of Python-macro.

Specificatie GlobalScope

Programmeren met Python-scripts

uno.fileUrlToSystemPath()

uno.systemPathToFileUrl()

I/O op scherm met Python (wiki)

XSCRIPTCONTEXT.getComponentContext()

uno.getComponentContext()

platform.system()

os.pathsep()