Služba ScriptForge.Basic

Záměrem služby ScriptForge.Basic je, aby šla v kontextu Pythonu spouštět vybraná sada metod jazyka LibreOffice Basic. Metody služby Basic přesně reprodukují syntaxi a chování funkcí vestavěných v Basicu.

Typický příklad:


   bas.MsgBox('Zobrazit ze skriptu Pythonu tento text v dialogu')

Služba ScriptForge.Basic je omezena na skripty Pythonu.

Volání služby

Před použitím služby Basic naimportujte metodu CreateScriptService() z modulu scriptforge:


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

Vlastnosti

Název	Pouze pro čtení	Typ	Popis
MB_OK, MB_OKCANCEL, MB_RETRYCANCEL, MB_YESNO, MB_YESNOCANCEL	ano	Integer	Hodnoty: 0, 1, 5, 4, 3
MB_ICONEXCLAMATION, MB_ICONINFORMATION, MB_ICONQUESTION, MB_ICONSTOP	ano	Integer	Hodnoty: 48, 64, 32, 16
MB_ABORTRETRYIGNORE, MB_DEFBUTTON1, MB_DEFBUTTON2, MB_DEFBUTTON3	ano	Integer	Hodnoty: 2, 128, 256, 512
IDABORT, IDCANCEL, IDIGNORE, IDNO, IDOK, IDRETRY, IDYES	ano	Integer	Hodnoty: 3, 2, 5, 7, 1, 4, 6 Konstanty označující vybrané tlačítko pro MsgBox.
StarDesktop	ano	objekt UNO	Vrátí objekt StarDesktop představující aplikaci LibreOffice.
ThisComponent	ano	objekt UNO	Jestliže aktuální komponenta odkazuje na dokument LibreOffice, tato metoda vrátí objekt UNO, který tento dokument reprezentuje. Pokud aktuální komponenta neodpovídá žádnému dokumentu, metoda vrátí None.
ThisDatabaseDocument	ano	objekt UNO	Pokud je skript spuštěn z dokumentu Base nebo některé z jeho dílčích komponent, vrátí tato metoda hlavní komponentu instance Base. V ostatních případech tato metoda vrátí None.

Seznam metod služby 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

Převede číselný výraz nebo řetězec na nativní objekt Pythonu datetime.datetime.

Tato metoda zpřístupňuje skriptům Pythonu vestavěnou funkci Basicu CDate.

Syntaxe:

svc.CDate(expression: any): obj

Parametry:

expression: číselný výraz nebo řetězec představující datum.

Při převádění řetězce musí být datum a čas zadáno buď podle některé z masek pro rozpoznání data stanovených v národním nastavení ( - Jazyky a národní prostředí - Obecné), nebo ve formátu data podle normy ISO (prozatím je povolený pouze formát ISO se spojovníky, např. "2012-12-31"). V číselných výrazech představuje část vlevo od desetinné čárky datum (počítáno od 31. prosince 1899) a část vpravo od desetinné čárky představuje čas.

Příklad:


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

CDateFromUnoDateTime

Převede reprezentaci data/času v UNO na nativní objekt Pythonu datetime.datetime.

Syntaxe:

svc.CDateFromUnoDateTime(unodate: uno): obj

Parametry:

unodate: Objekt UNO data/času, některý z následujících typů: com.sun.star.util.DateTime, com.sun.star.util.Date nebo com.sun.star.util.Time

Příklad:

V následujícím příkladu je vytvořen objekt com.sun.star.util.DateTime, který se převede na objekt Pythonu 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

Převede reprezentaci data na objekt com.sun.star.util.DateTime.

Syntaxe:

svc.CDateToUnoDateTime(date: obj): uno

Parametry:

date: Objekt Pythonu data/času, některý z následujících typ: datetime.datetime, datetime.date, datetime.time, float (time.time) nebo time.struct_time.

Příklad:


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

Parametry:

interval: Řetězec z následující tabulky, který určuje interval data nebo času.

Interval (řetězec)	Vysvětlení
yyyy	Rok
q	Čtvrtletí
m	Měsíc
y	Den v roce
w	Den v týdnu
ww	Týden v roce
d	Den
h	Hodina
n	Minuta
s	Sekunda

number: Číselný výraz, který určuje, kolikrát se má interval přidat (number je kladné) nebo odebrat (number je záporné).

date: Hodnota datetime.datetime, k níž se přidá hodnota interval, a to numberkrát.

Návratová hodnota:

Hodnota datetime.datetime.

Příklad:


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

DateDiff

Vrátí počet intervalů mezi dvěma daty/časy.

Syntaxe:

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

Parametry:

interval: Řetězec, který určuje interval, jak je popsáno u metody DateAdd.

date1, date2: Dvě hodnoty datetime.datetime, které se mají porovnat.

firstdayofweek: Nepovinný parametr, který určuje první den v týdnu.

Hodnota firstdayofweek	Vysvětlení
0	Použít výchozí systémovou hodnotu
1	Neděle (výchozí)
2	Pondělí
3	Úterý
4	Středa
5	Čtvrtek
6	Pátek
7	Sobota

firstweekofyear: Nepovinný parametr, který určuje první týden v roce.

Hodnota firstweekofyear	Vysvětlení
0	Použít výchozí systémovou hodnotu
1	První týden je ten, který obsahuje 1. leden (výchozí)
2	První týden je ten, který obsahuje alespoň čtyři dny roku
3	První týden je ten, který obsahuje pouze dny z nového roku

Návratová hodnota:

Číslo.

Příklad:


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

DatePart

Funkce DatePart vrátí určenou část data.

Syntaxe:

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

Parametry:

interval: Řetězec, který určuje interval, jak je popsáno u metody DateAdd.

date: Datum/čas, ze kterého se má vypočítat výsledek.

firstdayofweek, firstweekofyear: nepovinné parametry určující první den v týdnu a první týden v roce, jak je popsáno výše u metody DateDiff.

Návratová hodnota:

Požadovaná část zadaného data/času.

Příklad:


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

DateValue

Vypočítá datum z data zadaného jako řetězec.

Syntaxe:

svc.DateValue(date: str): datetime

Parametry:

date: Řetězec obsahující datum, které se převede na objekt Date.

Je nutné, aby byl řetězec předaný funkci DateValue vyjádřen v některém z formátů data definovaných v nastavení národního prostředí (viz - Jazyky a národní prostředí - Obecné) nebo formátem data standardu ISO ve tvaru "yyyy-mm-dd" (rok, měsíc a den oddělené spojovníky).

Návratová hodnota:

Vypočtené datum.

Příklad:


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

Format

Převede číslo na řetězec a ten upraví podle zadaného formátu.

Syntaxe:

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

Parametry:

expression: Číselný výraz, který chcete převést na formátovaný řetězec.

format: Řetězec, který určuje formátovací kód pro číslo. Je-li format vynechán, funguje funkce Format podobně jako funkce LibreOffice Basic Str().

Návratová hodnota:

Textový řetězec.

Formátovací kódy

Následující seznam popisuje kódy, které je možné použít k formátování číselného výrazu:

0: Pokud má expression na pozici, kde je v kódu format 0, číslici, zobrazí se číslice, jinak se zobrazí nula.

Pokud má expression méně číslic, než je počet nul v kódu format (před či za desetinnou čárkou), zobrazí se nuly navíc na začátku nebo na konci. Pokud má expression před desetinnou čárkou více číslic než počet nul v kódu format, číslice navíc se zobrazí bez formátování.

Desetinná část hodnoty expression se zaokrouhlí podle počtu nul, které jsou kódu format za desetinným oddělovačem.

#: Pokud expression obsahuje v kódu format na pozici znaku # číslici, tato číslice se zobrazí, jinak se na této pozici nezobrazí nic.

Tento symbol má stejnou funkci jako 0, kromě toho, že se úvodní a koncové nuly nezobrazí, je-li v kódu format více znaků # než číslic v expression. Zobrazí se pouze relevantní číslice daného výrazu expression.

.: Zástupný znak pro desetinný oddělovač.

Pokud kód format obsahuje zástupné znaky # pouze nalevo od tohoto symbolu, budou čísla menší než 1 začínat desetinnou čárkou. Pokud chcete u zlomkových čísel vždy zobrazit úvodní nulu, použijte 0 jako zástupný znak pro první číslici nalevo od desetinné čárky.

%: Vynásobí expression číslem 100 a vloží znak procenta (%) na místo, kde se expression nachází v kódu format.

E- E+ e- e+ : Pokud kód format obsahuje alespoň jeden zástupný znak pro číslici (0 nebo #) napravo do symbolu E-, E+, e- nebo e+, expression se naformátuje podle vědeckého (exponenciálního) formátu. Mezi číslo a exponent se vloží písmeno E nebo e. Počet zástupných znaků vpravo symbolu určuje počet číslic exponentu.

Je-li exponent záporný, zobrazí se bezprostředně před exponentem s E-, E+, e-, e+ znaménko minus. Je-li exponent kladný, zobrazí se znaménko plus pouze před exponenty s E+ nebo e+.

Oddělovač tisíců se zobrazí, pokud kód format obsahuje oddělovač obklopený zástupnými znaky pro číslice (0 nebo #).

Použití tečky jako oddělovače tisíců nebo desetinného oddělovače závisí na místním nastavení. Když zadáváte číslo přímo do kódu Basic, vždy používejte tečku jako desetinný oddělovač. Podle místního nastavení vašeho systému se zobrazí skutečný desetinný oddělovač.

- + $ ( ) mezera: Plus (+), mínus (-), dolar ($), mezera nebo závorky zadané v kódu format se zobrazí jako znaky.

Chcete-li zobrazit jiné znaky, musíte jim předřadit zpětné lomítko (\) nebo je uzavřít do uvozovek (" ").

\ : Zpětné lomítko zobrazí přímo další znak v kódu format.

Znaky v kódu format, které mají zvláštní význam, lze jako znaky zobrazit, pouze pokud před ně přidáte zpětné lomítko. Samotné zpětné lomítko se nezobrazí, pokud nezapíšete dvojité zpětné lomítko (\\).

Znaky, před které musíte přidat zpětné lomítko, aby se zobrazily přímo jako znaky, jsou formátovací znaky pro datum a čas (a, c, d, h, m, n, p, q, s, t, w, y, /, :), formátovací znaky pro čísla (#, 0, %, E, e, čárka, tečka) a formátovací znaky pro řetězce (@, &, <, >, !).

Také je možné použít následující předem definované formáty čísla. Kromě "General Number" se všechny předem definované formáty zobrazují jako čísla zaokrouhlená na dvě desetinná místa.

Pokud používáte předem definované formáty, musí být název formátu uveden v uvozovkách.

Předem definované formáty

General Number: Čísla se zobrazí, jak jsou zadána.

Currency: Vloží před číslo znak dolaru a záporná čísla uzavře do závorek.

Fixed: Zobrazí před desetinným oddělovačem alespoň jednu číslici.

Standard: Zobrazí čísla s oddělovačem tisíců.

Percent: Vynásobí číslo 100 a přidá k číslu znak procent.

Scientific: Zobrazí čísla ve vědeckém formátu (např. 1.00E+03 místo 1000).

Kód format lze rozdělit na tři části oddělené středníky. První část určuje formát pro kladná čísla, druhá pro záporná čísla a třetí pro nulu. Pokud určíte jen jeden kód format, použije se pro všechna čísla.

Národní prostředí použité pro formátování čísel, dat a měny v jazyce LibreOffice Basic můžete nastavit v - Jazyky a národní prostředí - Obecné. Ve formátovacích kódech se jako zástupný znak pro desetinný oddělovač používá vždy tečka (.), která se při zobrazení nahradí odpovídajícím znakem podle národního prostředí.

Totéž platí pro národní prostředí formátu data, času a měny. Formátovací kódy se interpretují a zobrazí podle aktuálního národního prostředí.

Příklad:


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

GetDefaultContext

Vrátí výchozí kontext process service factory, pokud existuje, jinak vrátí null.

GetDefaultContext je alternativou metody getComponentContext(), dostupné z globální proměnné XSCRIPTCONTEXT nebo z modulu uno.py.

Syntaxe:

svc.GetDefaultContext(): uno

Návratová hodnota:

Výchozí kontext pro komponentu se používá při vytváření instancí služeb pomocí XMultiServiceFactory. Další informace naleznete v kapitole Professional UNO příručky Developer's Guide na api.libreoffice.org.

Příklad:


    ctx = bas.GetDefaultContext()

GetGuiType

Vrátí číselnou hodnotu určující grafické uživatelské rozhraní. Tato funkce je k dispozici kvůli zpětné kompatibilitě s předchozími verzemi.

Chcete-li rozpoznat operační systém, použijte metodu system() z modulu Pythonu platform.

Syntaxe:

svc.GetGuiType(): int

Příklad:


    n = bas.GetGuiType()

GetPathSeparator

Vrátí na operačním systému závislý oddělovač adresářů používaný při určování cesty k souboru.

Pro rozpoznání oddělovače pro cestu použijte os.pathsep z modulu Pythonu os.

Syntaxe:

svc.GetPathSeparator(): str

Příklad:


    sep = bas.GetPathSeparator()

GetSystemTicks

Vrátí počet systémových tiků operačního systému. Tuto funkci je možné použít k optimalizaci některých procesů. Pomocí této metody odhadnete čas v milisekundách.

Syntaxe:

svc.GetSystemTicks(): int

Příklad:


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

GlobalScope.BasicLibraries

Vrátí objekt UNO obsahující všechny sdílené knihovny a modulu Basicu.

Tato metoda v Pythonu odpovídá metodě GlobalScope.BasicLibraries ve skriptech Basicu.

Syntaxe:

svc.GlobalScope.BasicLibraries(): uno

Návratová hodnota:

com.sun.star.script.XLibraryContainer

Příklad:

V následujícím příkladu je načtena knihovna Basicu Gimmicks, pokud již nebyla načtena dříve.


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

GlobalScope.DialogLibraries

Vrátí objekt UNO obsahující všechny sdílené knihovny dialogových oken.

Tato metoda v Pythonu odpovídá metodě GlobalScope.DialogLibraries ve skriptech Basicu.

Syntaxe:

svc.GlobalScope.DialogLibraries(): uno

Návratová hodnota:

com.sun.star.comp.sfx2.DialogLibraryContainer

Příklad:

V následujícím příkladu se zobrazí dialog s názvy všech dostupných knihoven dialogových oken.


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

InputBox

Syntaxe:

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

Parametry:

prompt: Řetězec, který se zobrazí jako zpráva v dialogovém okně.

title: Řetězec, který se zobrazí v záhlaví dialogového okna.

default: Řetězec, který se zobrazí v textovém poli jako výchozí, pokud není zadán vstup.

xpostwips: Celočíselný výraz, který určuje vodorovné umístění dialogu. Pozice je absolutní souřadnice a nevztahuje se k oknu aplikace.

ypostwips: Celočíselný výraz, který určuje svislé umístění dialogu. Pozice je absolutní souřadnice a nevztahuje se k oknu aplikace.

Pokud jsou pozice xpostwips a ypostwips vynechány, dialog se na obrazovce zarovná na střed. Pozice se určuje v twipech.

Návratová hodnota:

String

Příklad:


    txt = s.InputBox('Zadejte heslo:', "Drahý uživateli")
    s.MsgBox(txt, s.MB_ICONINFORMATION, "Potvrzení hesla")

Podrobné informace naleznete na wiki stránce Input/Output to Screen with Python.

MsgBox

Zobrazí dialog obsahující zprávu a volitelně vrátí hodnotu.
Konstanty MB_xx popisují typ dialogu, počet a typ zobrazených tlačítek a typ ikony. Jejich hodnoty tvoří bitový vzorek, který určuje vzhled dialogu MsgBox.

Syntaxe:

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

Parametry:

prompt: Řetězec zobrazený jako zpráva v dialogovém okně. Zalomení řádku lze vložit pomocí Chr$(13).

title: Řetězec zobrazený v záhlaví dialogového okna. Je-li vynechán, zobrazí se v záhlaví název odpovídající aplikace.

buttons: Jakýkoliv celočíselný výraz, který určuje druh dialogu a také počet a druh zobrazených tlačítek a druh ikony. buttons představuje kombinaci bitových vzorků, takže lze použít kombinaci prvků součtem jejich hodnot:

Návratová hodnota:

Volitelné celé číslo popsané výše u vlastnosti IDxx.

Příklad:


    txt = s.InputBox('Zadejte heslo:', "Drahý uživateli")
    s.MsgBox(txt, s.MB_ICONINFORMATION, "Potvrzení hesla")

Podrobné informace naleznete na wiki stránce Input/Output to Screen with Python.

Now

Vrátí aktuální systémový datum a čas jako nativní objekt Pythonu datetime.datetime.

Syntaxe:

svc.Now(): datetime

Příklad:


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

RGB

Vrátí celočíselnou hodnotu typu složenou z hodnot modré, červené a zelené složky.

Syntaxe:

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

Parametry:

red: Celočíselný výraz reprezentující červenou složku (0–255) barvy.

green: Celočíselný výraz reprezentující zelenou složku (0–255) barvy.

blue: Celočíselný výraz reprezentující modrou složku (0–255) barvy.

Výsledná hodnota typu Long je vypočítána podle následujícího vzorce:
Výsledek = red×65536 + green×256 + blue.

V režimu kompatibility s VBA (Option VBASupport 1), je hodnota Long vypočítána jako:
Výsledek = red + green×256 + blue×65536
Viz funkce RGB [VBA]

Zjistit hodnoty červené, zelené a modré složky barvy lze pomocí dialogového okna pro výběr barvy. Toto okno zobrazíte volbou Vlastní barva při změně barvy textu.

Návratová hodnota:

Integer

Příklad:


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

Xray

Prozkoumá objekty UNO nebo proměnné.

Syntaxe:

svc.Xray(obj: any)

Parametry:

obj: Proměnná nebo objekt UNO.

Příklad:


    bas.Xray(bas.StarDesktop)

Všechny procedury nebo identifikátory knihovny ScriptForge, které jsou uvozeny podtržítkem "_", jsou určeny pro interní použití. Není zamýšleno je používat v makrech Basicu nebo skriptech Pythonu.

Specifikátor GlobalScope

Programování pomocí skriptů Pythonu

uno.fileUrlToSystemPath()

uno.systemPathToFileUrl()

Input/Output to Screen with Python na wiki

XSCRIPTCONTEXT.getComponentContext()

uno.getComponentContext()

platform.system()

os.pathsep()