Obsah

# 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í (LibreOffice - PředvolbyNástroje - Možnosti - 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))

## ConvertFromUrl

Vrátí cestu systému k souboru pro danou adresu URL s file:.

### Syntaxe:

svc.ConvertFromUrl(url: str): str

### Parametry:

url: Absolutní adresa URL s file:.

### Návratová hodnota:

Cesta systému s názvem souboru.

### Příklad:

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

## ConvertToUrl

Vrátí adresu URL s file: pro danou cestu systému.

### Syntaxe:

svc.ConvertToUrl(systempath: str): str

### Parametry:

systempath: Název souboru v systému jako řetězec.

### Návratová hodnota:

Adresa URL s file: jako řetězec.

### Příklad:

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

## CreateUnoService

Vytvoří instanci služby UNO se službou ProcessServiceManager.

### Syntaxe:

svc.CreateUnoService(servicename: str): uno

### Parametry:

servicename: Plně kvalifikovaný název služby, například com.sun.star.ui.dialogs.FilePicker či com.sun.star.sheet.FunctionAccess.

### Příklad:

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

## CreateUnoStruct

Vrátí instanci struktury UNO zadaného typu.

### Syntaxe:

svc.CreateUnoStruct(unostructure: str): uno

### Parametry:

unostructure: Plně kvalifikovaný název struktury, například com.sun.star.beans.Property nebo com.sun.star.util.DateTime.

### Příklad:

        date_struct = CreateUnoStruct('com.sun.star.util.DateTime')

## DateAdd

Přidá k určenému datu/času interval (se zadaným počtem opakování) a vrátí výsledné datum.

### Syntaxe:

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

### 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 LibreOffice - PředvolbyNástroje - Možnosti - 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 LibreOffice - PředvolbyNástroje - Možnosti - 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ězcový výraz, 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.

Související témata

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