Storitev ScriptForge.Basic

Storitev ScriptForge.Basic ponuja zbirko metod LibreOffice Basic, ki jih je moč izvajati v kontekstu Pythona. Metode storitve Basic imajo isto skladnjo in vedenje kot vgrajene funkcije Basica.

Značilen primer:


   bas.MsgBox('Prikaži to besedilo v sporočilu iz skripta Python.')

Storitev SFDocuments.Basic je omejena na skripte Python.

Priklic storitve

Pred uporabo storitve Basic je potrebno uvoziti metodo CreateScriptService() iz modula scriptforge:


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

Lastnosti

Ime	Samo za branje	Vrsta	Opis
MB_OK, MB_OKCANCEL, MB_RETRYCANCEL, MB_YESNO, MB_YESNOCANCEL	Da	Integer	Vrednosti: 0, 1, 5, 4, 3
MB_ICONEXCLAMATION, MB_ICONINFORMATION, MB_ICONQUESTION, MB_ICONSTOP	Da	Integer	Vrednosti: 48, 64, 32, 16
MB_ABORTRETRYIGNORE, MB_DEFBUTTON1, MB_DEFBUTTON2, MB_DEFBUTTON3	Da	Integer	Vrednosti: 2, 128, 256, 512
IDABORT, IDCANCEL, IDIGNORE, IDNO, IDOK, IDRETRY, IDYES	Da	Integer	Vrednosti: 3, 2, 5, 7, 1, 4, 6 Konstante, ki nakazujejo izbrani gumb v MsgBox.
StarDesktop	Da	Predmet UNO	Vrne Predmet StarDesktop, ki predstavlja program LibreOffice.
ThisComponent	Da	Predmet UNO	Če se trenutna komponenta nanaša na dokument LibreOffice, ta metoda vrne predmet UNO, ki predstavlja dokument. Ta lastnost vrne None, če trenutna komponenta ne ustreza dokumentu.
ThisDatabaseDocument	Da	Predmet UNO	Če se skript izvaja iz dokumenta programa Base ali ene od njegovih podkomponent, ta metoda vrne glavno komponento instance Base. Ta lastnost sicer vrne None.

Seznam metod v storitvi 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

Pretvori numerični izraz ali niz v domorodni predmet Pythona datetime.datetime.

Ta metoda razkrije vgrajeno funkcijo Basic CDate v skriptih Python.

Skladnja:

svc.CDate(expression: any): obj

Parametri:

izraz: numeričen izraz ali niz, ki predstavlja datum.

Kadar pretvorite niz, morajo biti datumi in časi zapisani v enem od definiranih vzorcev datuma za vašo krajevno nastavitev (glejte – Jeziki in področne nastavitve – Splošno) ali v zapisu datuma po standardu ISO (trenutno je podprt le zapis ISO z vezaji, npr. »2012-12-31«). V numeričnih izrazih predstavljajo vrednosti levo od decimalne vejice datum od 31. decembra 1899 dalje. Vrednosti desno od decimalne vejice predstavljajo čas.

Primer:


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

CDateFromUnoDateTime

Pretvori reprezentacijo datuma/časa UNO v domorodni predmet Pythona datetime.datetime.

Skladnja:

svc.CDateFromUnoDateTime(unodate: uno): obj

Parametri:

unodate: predmet datuma/časa UNO ene od naslednjih vrst: com.sun.star.util.DateTime, com.sun.star.util.Date ali com.sun.star.util.Time.

Primer:

Spodnji primer ustvari predmet com.sun.star.util.DateTime in ga pretvori v predmet Pythona datetime.datetime.


    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

Pretvori reprezentacijo datuma v predmet com.sun.star.util.DateTime.

Skladnja:

svc.CDateToUnoDateTime(date: obj): uno

Parametri:

date: Pythonov predmet datuma/časa ene od naslednjih vrst: datetime.datetime, datetime.date, datetime.time, float (time.time) ali time.struct_time.

Primer:


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

Parametri:

interval: niz iz naslednje tabele, ki definira datumsko ali časovno razdobje.

interval (niz)	Razlaga
yyyy	Leto
q	Četrtletje
m	Mesec
y	Dan v letu
w	Delavnik
ww	Teden v letu
d	Dan
h	Ura
n	Minuta
s	Sekunda

number (števec): numerični izraz, ki pove, kolikokrat se interval interval prišteje (ko je pozitiven) ali odšteje (ko je negativen).

date (datum): dana datumsko-časovna vrednost (datetime.datetime); vrednost interval bo tej vrednosti dodana tolikokrat, kolikor znaša number.

Vrnjena vrednost:

Datumska/časovna vrednost datetime.datetime.

Primer:


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

DateDiff

Vrne število datumskih ali časovnih intervalov med podanima datumskima/časovnima vrednostma.

Skladnja:

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

Parametri:

interval: niz, ki definira datumsko ali časovno razdobje, kot je opredeljeno v zgornji metodi DateAdd.

date1, date2: vrednosti datuma datetime.datetime, ki ju primerjate.

PrviDanTedna: neobvezni parameter, ki določa začetni dan v tednu.

Vrednost za prviDanTedna	Razlaga
0	Uporabi privzeto sistemsko vrednost
1	Nedelja (privzeto)
2	Ponedeljek
3	Torek
4	Sreda
5	Četrtek
6	Petek
7	Sobota

prviTedenLeta: neobvezni parameter, ki določa začetni teden v letu.

Vrednost za prviTedenLeta	Razlaga
0	Uporabi privzeto sistemsko vrednost
1	Teden 1 je teden s prvim januarjem (privzeto)
2	Teden 1 je prvi teden v letu, ki ima štiri ali več dni.
3	Teden 1 je prvi teden, za katerega so vsi dnevi v novem letu.

Vrnjena vrednost:

Število.

Primer:


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

DatePart

Funkcija DatePart vrača zahtevani del datuma.

Skladnja:

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

Parametri:

interval: niz, ki definira datumsko ali časovno razdobje, kot je opredeljeno v zgornji metodi DateAdd.

date (datum): datum/čas, iz katerega se izračuna rezultat.

firstdayofweek, firstweekofyear: neobvezna parametra, ki določata začetni dan tedna in začetni teden leta, kar je podrobneje pojasnjeno pri zgornji metodi DateDiff.

Vrnjena vrednost:

Izvlečeni del podanega datuma/časa.

Primer:


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

DateValue

Izračuna datumsko vrednost iz datumskega niza.

Skladnja:

svc.DateValue(date: str): datetime

Parametri:

datum: niz, ki vsebuje datum, ki ga želite pretvoriti v predmet Date.

Niz, podan DateValue, mora biti zapisan v eni od datumskih oblik, ki so določene za vaše krajevne nastavitve (glejte – Jeziki in področne nastavitve – Splošno), ali z uporabo datumskega zapisa ISO »llll-mm-dd« (letnica, mesec in dan, ločeni z vezaji).

Vrnjena vrednost:

Izračunani datum.

Primer:


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

Format

Pretvori število v niz in ga potem oblikuje v skladu z obliko, ki jo navedete.

Skladnja:

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

Parametri:

Izraz: numerični izraz, ki ga želite pretvoriti v oblikovan niz.

Oblika: Niz, ki določa kodo za oblikovanje števila. Če parametra oblika ne navedete, bo funkcija Format dala isti rezultat kot funkcija LibreOffice Str().

Vrnjena vrednost:

Besedilni niz.

Kode za oblikovanje

Naslednji seznam navaja kode, ki jih lahko uporabljate za oblikovanje številskih izrazov:

0: Če ima izraz števko na mestu, kjer se nahaja 0 v kodi oblika, se prikaže števka, sicer pa ničla.

Če ima izraz manj mest, kot je ničel v kodi za oblikovanje oblika (na obeh straneh decimalne vejice), bo imel rezultat vodeče ali sledeče ničle. Če ima izraz na levi strani decimalnega ločila več mest, kot je ničel v kodi za oblikovanje oblika, bodo dodatne cifre izpisane neoblikovano.

Decimalna mesta v izrazu se zaokrožajo v skladu s številom ničel, ki se nahajajo za decimalnim ločilom v kodi oblika.

#: Če vsebuje izraz cifro na mestu, kjer se nahaja v kodi oblikovanja oblika nahaja ograda #, se na tem mestu izpiše cifra, sicer pa nič.

Ta simbol deluje tako kot 0, samo da se vodečih ali sledečih ničel ne kaže, če je v kodi za oblikovanje oblika več znakov # kot pa mest v izrazu. Prikazana so samo pomembna mesta v izrazu.

.: Znak za decimalno ločilo določa število decimalnim mest levo in desno od decimalnega ločila.

Če koda za oblikovanje oblika vsebuje samo znake # levo od tega simbola, se rezultat za števila, manjša od 1, začenja z decimalnim ločilom. Uporabite znak 0 za prvo mesto levo od decimalnega ločila, da bodo v tem primeru števila izpisana z vodilno ničlo.

%: pomnoži izraz s 100 in na mestu, kjer se izraz v kodi za oblikovanje oblika nahaja, vrine znak za odstotek (%).

E- E+ e- e+ : Če koda za oblikovanje oblika vsebuje najmanj en znak (0 or #) desno od simbola E-, E+, e-, or e+, se bo izraz izpisal v znanstveni ali eksponentni obliki. Med število in eksponent se vstavi črka E oziroma e. Število znakov za mesta desno od simbola določa, koliko znakov bo imel eksponent.

Če je eksponent negativen, se za E-, E+, e-, e+ znak minus izpiše neposredno pred eksponent. Če je eksponent pozitiven, se znak plus piše pred eksponente samo v primeru E+ or e+.

Ločilo za tisočice se vstavlja, če koda za oblikovanje oblika vsebuje ločilo, vključeno med znake za cifre (0 ali #).

Ali se pika uporablja kot ločilo za tisoče ali za decimalke, je odvisno od področne nastavitve. Kadar vnašate število neposredno v izvorno kodo za Basic, za decimalno ločilo vedno uporabljajte piko. Kateri znak se bo dejansko uporabil, je odvisno od numeričnega oblike v sistemskih nastavitvah.

- + $ ( ) presledek: Znaki plus (+), minus (-), dolar ($), presledek ali oklepaji, ki so neposredno vneseni v oblikovni kodi oblika, se prikažejo dobesedno.

Če želite prikazati kake druge znake, jim morate predpisati poševnico (\), ali pa jih obdati z narekovaji (" ").

\ : poševnica izpiše naslednji znak v kodi za oblikovanje oblika.

Znake v kodi za oblikovanje oblika, ki imajo poseben pomen, je mogoče prikazati take kot so, samo če prednje zapišete poševnico. Poševnica se pri tem ne izpiše, razen če ne vpišete dvojno poševnico (\\) v kodo za oblikovanje.

Če želite dobeseden izpis, moramo postaviti poševnico pred znake za oblikovanje datuma in časa (a, c, d, h, m, n, p, q, s, t, w, y, /, :) , pred znake, s katerimi se oblikujejo števila (#, 0, %, E, e, vejica, pika), in pred znake za oblikovanje nizov (@, &, <, >, !).

Lahko uporabljate tudi naslednje vnaprej določene oblike za števila. Razen oblike »General Number« vse vrnejo vnaprej določene oblike število v obliki decimalnega števila z dvema decimalnima mestoma.

Če uporabljate vnaprej določene oblike, morate ime oblike postaviti v narekovaje.

Vnaprej določene oblike

General Number: Števila se kaže, kot so bila vnesena.

Currency: pred število postavi znak za valuto, negativna števila vstavi v oklepaj.

Fixed: pred decimalno ločilo postavi najmanj eno cifro.

Standard: prikazuje števila z ločilo za tisočice.

Percent: Zmnoži število s 100 in mu prida znak za odstotek.

Scientific: prikaže števila v znanstveni obliki (npr. 1,00E+03 za 1000).

Kodo za oblikovanje oblika je mogoče razdeliti v tri odseke, ki so med seboj ločeni z vejicami. Prvi del definira obliko za pozitivna števila, drugi del za negativna števila, tretji del pa za nič. Če navedete samo eno kodo za obliko oblika, se jo bo uporabilo za vsa števila.

Področne nastavitve, ki se uporabljajo za obliko števil, datumov in valute v LibreOffice Basicu, lahko nastavite v – Jeziki in področne nastavitve – Splošno. V kodah zapisov Basica je decimalna pika (.) vedno uporabljena kot ograda za desetiško ločilo, določeno z vašo področno nastavitvijo in bo kasneje zamenjana z ustreznim znakom.

Enako velja za področne nastavitve oblike datuma, časa in valute. Oblika zapisa Basica bo prevedena in prikazana glede na vaše področne nastavitve.

Primer:


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

GetDefaultContext

Vrne privzeti kontekst tovarne za procesne storitve (process service factory), če obstaja, v nasprotnem primeru vrne ničelni sklic (null).

GetDefaultContext je alternativa za metodo getComponentContext(), ki je na voljo pri globalni spremenljivki XSCRIPTCONTEXT ali v modulu uno.py.

Skladnja:

svc.GetDefaultContext(): uno

Vrnjena vrednost:

Privzeti kontekst komponente se uporabi, kadar tvorite instance storitve prek XMultiServiceFactory. Podrobnosti si oglejte v poglavju Professional UNO v vodniku za razvijalce (Developer's Guide) na api.libreoffice.org (v angl.).

Primer:


    ctx = bas.GetDefaultContext()

GetGuiType

Vrne numerično vrednost, ki določa grafični uporabnikov vmesnik. Ta funkcija je omogočena zgolj za združljivost s starejšimi različicami.

Glejte metodo system() iz modula Python platform za prepoznavanje operacijskega sistema.

Skladnja:

svc.GetGuiType(): int

Primer:


    n = bas.GetGuiType()

GetPathSeparator

Vrne ločilo map za določanje poti datotek, kot ga določa operacijski sistem.

uporabite os.pathsep iz modula Python os za identifikacijo ločila poti.

Skladnja:

svc.GetPathSeparator(): str

Primer:


    sep = bas.GetPathSeparator()

GetSystemTicks

Vrne število tikov, kot jih nudi operacijski sistem. Z njihovo pomočjo lahko optimizirate določene procese. Uporabite to metodo za oceno časa v milisekundah:

Skladnja:

svc.GetSystemTicks(): int

Primer:


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

GlobalScope.BasicLibraries

Vrne predmet UNO, ki vsebuje vse knjižnice in module Basic v skupni rabi.

Ta metoda je Pythonov ekvivalent za GlobalScope.BasicLibraries v skriptih Basic.

Skladnja:

svc.GlobalScope.BasicLibraries(): uno

Vrnjena vrednost:

com.sun.star.script.XLibraryContainer

Primer:

Naslednji primer naloži Gimmicks, knjižnico Basic, če še ni naložena.


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

GlobalScope.DialogLibraries

Vrne predmet UNO, ki vsebuje vse knjižnice pogovornih oken v skupni rabi.

Ta metoda je Pythonov ekvivalent za GlobalScope.DialogLibraries v skriptih Basic.

Skladnja:

svc.GlobalScope.DialogLibraries(): uno

Vrnjena vrednost:

com.sun.star.comp.sfx2.DialogLibraryContainer

Primer:

Naslednji primer prikaže okno z imeni vseh knjižnic pogovornih oken, ki so na voljo.


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

InputBox

Skladnja:

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

Parametri:

Poziv: niz, ki se prikaže kot sporočilo v pogovornem oknu.

Naslov: niz, prikazan v naslovni vrstici pogovornega okna.

Privzeto: niz, prikazan kot privzeto besedilo v polju za besedilo, če uporabnik ne vnese ničesar.

xPolTwipi: celoštevilski izraz, ki določa vodoravni položaj pogovornega okna. Položaj je absolutna koordinata in se ne nanaša na okno LibreOffice.

yPolTwipi: celoštevilski izraz, ki določa navpični položaj pogovornega okna. Položaj je absolutna koordinata in se ne nanaša na okno LibreOffice.

Če xPolTwipi in yPolTwipi izpustite, se bo pogovorno okno nahajalo na sredi zaslona. Položaj določimo v twipih.

Vrnjena vrednost:

String

Primer:


    txt = s.InputBox ('Prosimo, vnesite stavek:', "Dragi uporabnik")
    s.MsgBox(txt, s.MB_ICONINFORMATION, "Za potrditev stavka")

Podrobnosti si preberite v članku Vhod/izhod na zaslonu s Pythonom na wikiju (v angl.).

MsgBox

Prikaže pogovorno okno, ki vsebuje sporočilo in vrne neobvezno vrednost.
Konstante MB_xx pomagajo določiti vrsto pogovornega okna, število in vrsto prikazanih gumbov ter vrsto ikone. Z dodajanjem njihovih ustreznih vrednosti tvorijo bitne vzorce, ki določajo videz pogovornega okna MsgBox.

Skladnja:

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

Parametri:

Poziv: niz, ki se bo prikazal v pogovornem oknu kot sporočilo. Prelome v novo vrstico vnesete s Chr$(13).

Naslov: niz, prikazan v naslovni vrstici pogovornega okna. Če parameter izpustite, se bo v naslovni vrstici izpisalo ime aplikacije.

Gumbi: Izraz vrste Integer, ki definira vrsto pogovornega okna, in pa število in vrsto gumbov, ki bodo prikazani, ter vrsto ikon. Gumbi je kombinacija bitnih vzorcev, to je kombinacija elementov, ki so definirani tako, da njihove vrednosti lahko seštevamo:

Vrnjena vrednost:

Neobvezno celo število, kot je opisano v zgodnjih lastnostih IDxx.

Primer:


    txt = s.InputBox ('Prosimo, vnesite stavek:', "Dragi uporabnik")
    s.MsgBox(txt, s.MB_ICONINFORMATION, "Za potrditev stavka")

Podrobnosti si preberite v članku Vhod/izhod na zaslonu s Pythonom na wikiju (v angl.).

Now

Vrne trenutni sistemski datum in čas kot domorodni predmet Pythona datetime.datetime.

Skladnja:

svc.Now(): datetime

Primer:


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

RGB

Vrne celoštevilsko vrednost za barvo, sestavljeno iz rdeče, zelene in modre komponente.

Skladnja:

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

Parametri:

Rdeča: celoštevilski izraz, ki predstavlja rdeči delež (0-255) sestavljene barve.

Zelena: celoštevilski izraz, ki predstavlja zeleni delež (0-255) sestavljene barve.

Modra: celoštevilski izraz, ki predstavlja modri delež (0-255) sestavljene barve.

Končna vrednost Long se izračuna po naslednji formuli:
Rezultat = rdeča×65536 + zelena×256 + modra.

Če je omogočen združljivostni način VBA (Option VBASupport 1), se vrednost Long izračuna kot
Rezultat = rdeča + zelena×256 + modra×65536
Glejte Funkcija RGB [VBA].

Pogovorno okno Izberi barvo pomaga izračunati rdečo, zeleno in modro komponento kode sestavljene barve. S spreminjanjem barve besedila in izbiro Barva po meri odprete pogovorno okno izbirnika barv.

Vrnjena vrednost:

Integer

Primer:


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

Xray

Preveri predmete UNO ali spremenljivke.

Skladnja:

svc.Xray(obj: any)

Parametri:

obj: spremenljivka ali predmet UNO.

Primer:


    bas.Xray(bas.StarDesktop)

Vsi podprogrami ali identifikatorji ScriptForge Basic s predpono podčrtaja (»_«) so rezervirani za interno uporabo. Uporabi v makrih Basic ali skriptih Python niso namenjeni.

Določilnik GlobalScope

Programiranje s skripti Python

uno.fileUrlToSystemPath()

uno.systemPathToFileUrl()

Vhod/izhod na zaslonu s Pythonom na wikiju (v angl.).

XSCRIPTCONTEXT.getComponentContext()

uno.getComponentContext()

platform.system()

os.pathsep()