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.

note

Ta storitev je na voljo od LibreOffice 7.2 naprej.


Značilen primer:


   svc.MsgBox('To naj bo prikazano v oknu s sporočilom.')
  
warning

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

Lastnosti

Ime

Samo za branje

Vrsta

Opis

MB_OK, MB_OKCANCEL, MB_RETRYCANCEL, MB_YESNO, MB_YESNOCANCEL

Da

celo število

Vrednosti: 0, 1, 5, 4, 3

MB_ICONEXCLAMATION, MB_ICONINFORMATION, MB_ICONQUESTION, MB_ICONSTOP

Da

celo število

Vrednosti: 48, 64, 32, 16

MB_ABORTRETRYIGNORE, MB_DEFBUTTON1, MB_DEFBUTTON2, MB_DEFBUTTON3

Da

celo število

Vrednosti: 2, 128, 256, 512

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

Da

celo število

Vrednosti: 3, 2, 5, 7, 1, 4, 6
Konstante, ki nakazujejo izbrani gumb v MsgBox.

StarDesktop

Da

Predmet
UNO

Predmet StarDesktop predstavlja Začetno središče LibreOffice.


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

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

note

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 – Jezikovne nastavitve – Jeziki) 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 = svc.CDate(1000.25)
    svc.MsgBox(str(d)) # 1902-09-26 06:00:00
    svc.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.


    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

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 = svc.CDateToUnoDateTime(current_datetime)
    svc.MsgBox(str(uno_date.Year) + "-" + str(uno_date.Month) + "-" + str(uno_date.Day))
  

ConvertFromUrl

Vrne sistemsko datotečno pot za dani URL file:.

Skladnja:

svc.ConvertFromUrl(url: str): str

Parametri:

url: absolutni URL za file:.

Vrnjena vrednost:

Ime datoteke s sistemsko potjo.

Primer:


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

ConvertToUrl

Vrne URL datoteke file: za dano sistemsko pot.

Skladnja:

svc.ConvertToUrl(systempath: str): str

Parametri:

systempath: sistemsko ime datoteke kot niz.

Vrnjena vrednost:

URL file: kot niz.

Primer:


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

CreateUnoService

Instanco storitve UNO tvori z upraviteljem procesnih storitev ProcessServiceManager.

Skladnja:

svc.CreateUnoService(servicename: str): uno

Parametri:

servicename : povsem kvalificirano ime storitve, kot npr. »com.sun.star.ui.dialogs.FilePicker« ali »com.sun.star.sheet.FunctionAccess«.

Primer:


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

DateAdd

Prišteje razdobje (datum ali čas) navedenemu datumu/času tolikokrat, kolikokrat je zahtevano, in vrne končni rezultat.

Skladnja:

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

Parametri:

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

interval (niz)

Razlaga

yyyy

Leto

q

Četrt

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

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

DateValue

Izračuna datumsko vrednost iz datumskega niza.

Skladnja:

svc.DateValue(date: str): datetime

Parametri:

Datum: niz ali izraz, ki vsebuje datum, s katerim želite računati. Za razliko od funkcije DateSerial, ki ji podate leta, mesece in dneve kot ločene številske vrednosti, zahteva funkcija DateValue datumski niz v enem od definiranih vzorcev datuma, določenih za vašo krajevno nastavitev (glejte – Jezikovne nastavitve – Jeziki), ali v zapisu datuma po standardu ISO (trenutno je podprt le zapis ISO z vezaji, npr. »2012-12-31«).

Vrnjena vrednost:

Izračunani datum.

Primer:


    dt = svc.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 – Nastavitve jezika – Jeziki. 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 = svc.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 = svc.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 = svc.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


    svc.GetPathSeparator(): str
  

Primer:


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


    tiki_ini = svc.GetSystemTicks()
    time.sleep(1)
    tiki_kon = svc.GetSystemTicks()
    svc.MsgBox("{} - {} = {}".format(tiki_kon, tiki_ini,tiki_kon - tiki_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 = svc.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 = svc.GlobalScope.DialogLibraries()
    lib_names = dlg_libs.getElementNames()
    svc.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:

niz

Primer:


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

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:

svc.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, MB_ICONINFORMATION, "Za potrditev stavka")
  
note

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:


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

tip

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:

celo število

Primer:


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

ThisComponent

Če se trenutna komponenta nanaša na dokument LibreOffice, ta metoda vrne predmet UNO, ki predstavlja dokument.

Ta metoda vrne None, če trenutna komponenta ne ustreza dokumentu.

Skladnja:

svc.ThisComponent(): uno

Primer:


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

ThisDatabaseDocument

Če se skript izvaja iz dokumenta programa Base ali ene od njegovih podkomponent, ta metoda vrne glavno komponento instance Base.

Metoda sicer vrne None.

Skladnja:

svc.ThisDatabaseDocument(): uno

Primer:


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

Obiščite stran API OfficeDatabaseDocument, da izveste več o strukturi glavne komponente Base.


Xray

Preveri predmete UNO ali spremenljivke.

Skladnja:

svc.Xray(obj: any)

Parametri:

obj: spremenljivka ali predmet UNO.

Primer:


    svc.Xray(svc.StarDesktop)
  
warning

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


Podprite nas!