Съдържание

# Услуга ScriptForge.Basic

Услугата ScriptForge предоставя съвкупност от методи на LibreOffice Basic за изпълнение в контекст на Python. Методите на услугата Basic възпроизвеждат точния синтаксис и поведение на вградените функции на Basic.

Типичен пример:

       bas.MsgBox('Показване на този текст от скрипт на Python')

Услугата ScriptForge.Basic е ограничена до скриптове на Python.

## Извикване на услугата

Преди да използвате услугата Basic, импортирайте метода CreateScriptService() от модула scriptforge:

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

## Свойства

Име | Само за четене | Тип | Описание
--- | --- | --- | ---
MB_OK, MB_OKCANCEL, MB_RETRYCANCEL, MB_YESNO, MB_YESNOCANCEL | Да | Integer | Стойности: 0, 1, 5, 4, 3
MB_ICONEXCLAMATION, MB_ICONINFORMATION, MB_ICONQUESTION, MB_ICONSTOP | Да | Integer | Стойности: 48, 64, 32, 16
MB_ABORTRETRYIGNORE, MB_DEFBUTTON1, MB_DEFBUTTON2, MB_DEFBUTTON3 | Да | Integer | Стойности: 2, 128, 256, 512
IDABORT, IDCANCEL, IDIGNORE, IDNO, IDOK, IDRETRY, IDYES | Да | Integer | Стойности: 3, 2, 5, 7, 1, 4, 6 Константи, показващи избрания бутон в MsgBox.
StarDesktop | Да | UNO обект | Връща обекта StarDesktop, който представя приложението LibreOffice.
ThisComponent | Да | UNO обект | Ако текущият компонент съответства на документ на LibreOffice, този метод връща UNO обекта, представящ документа. Това свойство връща None, когато текущият компонент не съответства на документ.
ThisDatabaseDocument | Да | UNO обект | Ако скриптът се изпълнява от документ на Base или някой от поддокументите му, този метод връща главния компонент на екземпляра на Base. В противен случай това свойство връща None.

Списък с методи на услугата 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

Преобразува числов израз или низ към вътрешен обект datetime.datetime на Python.

Този метод излага вградената функция на Basic CDate към скриптове на Python.

### Синтаксис:

svc.CDate(expression: any): obj

### Параметри:

expression: числов израз или низ, представящ дата.

Когато преобразувате низов израз, датата и часът трябва да съответстват или на някой от шаблоните за разпознаване, дефинирани в настройката за локал (вижте LibreOffice - Preferences Инструменти - Настройки - Езици и локали - Общи), или на формат на ISO за дата (в момента се приема само форматът с тиретата, напр. "2012-12-31"). В числовите изрази стойността вляво от десетичната запетая представя датата, започвайки от 31 декември 1899 г. Стойността вдясно от десетичната запетая представя часа.

### Пример:

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

## CDateFromUnoDateTime

Преобразува представяне на дата/час на UNO към вътрешен обект datetime.datetime на Python.

### Синтаксис:

svc.CDateFromUnoDateTime(unodate: uno): obj

### Параметри:

unodate: обект за дата/час на UNO от някой от следните типове: com.sun.star.util.DateTime, com.sun.star.util.Date или com.sun.star.util.Time.

### Пример:

Следващият пример създава обект от типа com.sun.star.util.DateTime и го преобразува към обект datetime.datetime на Python.

        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

Преобразува представяне на дата в обект com.sun.star.util.DateTime.

### Синтаксис:

svc.CDateToUnoDateTime(date: obj): uno

### Параметри:

date: обект за дата/час на Python от някой от следните типове: datetime.datetime, datetime.date, datetime.time, float (time.time) или time.struct_time.

### Пример:

        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

Връща системен път на файл за дадения URL от тип file:.

### Синтаксис:

svc.ConvertFromUrl(url: str): str

### Параметри:

url: абсолютен URL от типа file:.

### Резултат:

Системно файлово име с път.

### Пример:

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

## ConvertToUrl

Връща URL адрес от типа file: за дадения системен път.

### Синтаксис:

svc.ConvertToUrl(systempath: str): str

### Параметри:

systempath: системно име на файл като низ.

### Резултат:

URL от типа file: като низ.

### Пример:

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

## CreateUnoService

Връща екземпляр на UNO услуга от ProcessServiceManager.

### Синтаксис:

svc.CreateUnoService(servicename: str): uno

### Параметри:

servicename: напълно квалифицирано име на услуга, като com.sun.star.ui.dialogs.FilePicker или com.sun.star.sheet.FunctionAccess.

### Пример:

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

## CreateUnoStruct

Връща екземпляр на UNO структура от указания тип.

### Синтаксис:

svc.CreateUnoStruct(unostructure: str): uno

### Параметри:

unostructure: напълно квалифицирано име на структура, като com.sun.star.beans.Property или com.sun.star.util.DateTime.

### Пример:

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

## DateAdd

Добавя период от дати или часове към дадена дата/час определен брой пъти и връща получената дата.

### Синтаксис:

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

### Параметри:

interval: низова стойност от долната таблица, задаваща периода от дати или часове.

interval (низова стойност) | Обяснение
--- | ---
yyyy | Година
q | Тримесечие
m | Месец
y | Ден от годината
w | Ден от седмицата
ww | Седмица от годината
d | Ден
h | Час
n | Минута
s | Секунда

number: числов израз, задаващ колко пъти да се добави (ако е положителен) или извади (ако е отрицателен) стойността interval.

date: дадена стойност от тип datetime.datetime; стойността interval ще бъде добавена number пъти към тази стойност datetime.datetime.

### Резултат:

Стойност от типа datetime.datetime.

### Пример:

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

## DateDiff

Връща броя периоди от дати или часове между две зададени стойности – дати/часове.

### Синтаксис:

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

### Параметри:

interval: низов израз, указващ интервала от дати, както е описано по-горе за метода DateAdd.

date1, date2: двете стойности от типа datetime.datetime, които да бъдат сравнени.

firstdayofweek: незадължителен параметър, който задава началния ден на седмицата.

Стойност на firstdayofweek | Обяснение
--- | ---
0 | Използване на системните настройки
1 | Неделя (по подразбиране)
2 | Понеделник
3 | Вторник
4 | Сряда
5 | Четвъртък
6 | Петък
7 | Събота

firstweekofyear: незадължителен параметър, който задава началната седмица на годината.

Стойност на firstweekofyear | Обяснение
--- | ---
0 | Използване на системните настройки
1 | Седмица 1 е седмицата, съдъжаща 1 януари (по подразбиране).
2 | Седмица 1 е първата седмица, съдържаща четири или повече дни от съответната година.
3 | Седмица 1 е първата седмица, съдържаща само дни от новата година.

### Резултат:

Число.

### Пример:

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

## DatePart

Функцията DatePart връща зададена част от дата.

### Синтаксис:

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

### Параметри:

interval: низов израз, указващ интервала от дати, както е описано по-горе за метода DateAdd.

date: датата/часът, от който трябва да се изчисли резултатът.

firstdayofweek, firstweekofyear: незадължителни параметри, указващи съответно началния ден на седмицата и началната седмица на годината, както е описано по-горе за метода DateDiff.

### Резултат:

Извличаната част на дадената дата/час.

### Пример:

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

## DateValue

Изчислява стойност дата от низ с дата.

### Синтаксис:

svc.DateValue(date: str): datetime

### Параметри:

date: низ, съдържащ датата, която ще бъде преобразувана към обект от тип Date.

Низът, подаван към DateValue, трябва да е в някой от форматите, дефинирани от настройката за локал (вижте LibreOffice - Preferences Инструменти - Настройки - Езици и локали - Общи) или във формата за дати на ISO "yyyy-mm-dd" (година, месец и ден, разделени с късо тире).

### Резултат:

Изчислената дата.

### Пример:

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

## Format

Преобразува число в низ и го форматира по зададен от вас начин.

### Синтаксис:

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

### Параметри:

expression: числов израз, чиято стойност да се преобразува във форматиран низ.

format: низ, който указва кода на формат за числото. Ако параметърът format е пропуснат, функцията Format работи като функцията на LibreOffice Basic Str().

### Резултат:

Текстов низ.

### Кодове за форматиране

Следващият списък описва кодовете, които можете да използвате за форматиране на числов израз:

0: ако expression съдържа цифра в позицията на 0 в кода format, се показва цифрата, а в противен случай се показва нула.

Ако expression съдържа по-малко цифри от броя нули в кода format (в цялата и/или дробната част), се показват водещи или завършващи нули. Ако expression съдържа повече цифри в цялата си част, отколкото са нулите в кода format, допълнителните цифри се показват без форматиране.

Дробната част в expression се закръглява според броя нули вдясно от десетичния разделител в кода format.

#: ако expression съдържа цифра в позицията на заместителя # в кода format, се показва цифрата, иначе в тази позиция не се показва нищо.

Този знак работи като 0, но ако знаците # в кода format са повече от цифрите в expression, не се показват водещи или завършващи нули. Изписват се само значещите цифри от expression.

.: запазеното място за десетичен разделител определя броя на цифрите в вляво и вдясно от десетичния разделител.

Ако кодът format съдържа само знаци # вляво от този символ, числата, по-малки от 1, започват с десетичен разделител. За да се показва винаги 0 в началото на дробни числа, използвайте 0 като запазено място за първата цифра вляво от десетичния разделител.

%: умножава expression по 100 и вмъква знак за процент (%) там, където expression се намира в кода format.

E- E+ e- e+: ако кодът format съдържа поне един заместител за цифра (0 или #) вдясно от символа E-, E+, e- или e+, expression се форматира в експоненциален запис. Буквата E или e се вмъква между числото и експонентата. Броят заместващи знаци за цифри вдясно от символа определя броя на цифрите в експонентата.

Ако експонентата е отрицателна, точно преди нея се показва минус при E-, E+, e- и e+. Ако експонентата е положителна, при нея се показва знак плюс само при E+ или e+.

Разделителят на хилядите се показва, ако се съдържа в кода format, ограден от заместващи знаци за цифри (0 или #).

Употребата на точка като разделител на хилядите или на дробната част зависи от регионалните настройки. Когато въвеждате число направо в кода на Basic, винаги използвайте точка за разделител на дробната част. Знакът, който се показва на екрана като десетичен разделител, зависи от формата за числа в системните настройки.

- + $ ( ) интервал: плюс (+), минус (-), долар ($), интервал или скоби, пряко включени в кода format, се показват точно както са въведени.

За да включите други знаци освен изброените, трябва да поставите пред тях обратна наклонена черта (\) или да ги оградите с кавички (" ").

\ : обратно наклонената черта предизвиква показване на следващия знак от кода format.

Знаците в кода format, които имат специално значение, могат да се показват буквално само ако са предшествани от обратна наклонена черта. Самата тя не се показва, освен ако я въведете два пъти във форматиращия код (\\).

Знаците, пред които трябва да има обратно наклонена черта във форматиращия код, за да се покажат буквално, са тези за форматиране на дати и часове (a, c, d, h, m, n, p, q, s, t, w, y, /, :), за форматиране на числа (#, 0, %, E, e, запетая, точка) и за форматиране на низове (@, &, <, >, !).

Можете да използвате и изброените по-долу предварително дефинирани числови формати. С изключение на „General Number“ всички те връщат десетично число с две дробни позиции.

Ако използвате предварително дефинирани формати, името на формата трябва да е оградено в кавички.

### Предварително дефинирани формати

General Number: числата се показват както се въвеждат.

Currency: вмъква знак за долар пред числото и огражда отрицателните числа в скоби.

Fixed: показва поне една цифра пред десетичния разделител.

Standard: показва числата с разделител на хилядите.

Percent: умножава числото по 100 и добавя знак за проценти.

Scientific: показва числото в експоненциален запис (например 1.00E+03 за 1000).

Кодът format може да бъде разделен на три части с точки и запетаи. Първата част задава формата за положителни стойности, втората – за отрицателни и третата – за нули. Ако зададете само един код format , той важи за всякакви числа.

Локалът, използван за форматиране на числа, дати и парични суми в LibreOffice Basic, може да се задава в LibreOffice - Preferences Инструменти - Настройки - Езици и локали - Общи. Във форматиращите кодове на Basic десетичната точка (.) винаги се използва като заместител за дробния разделител от локала и се замества автоматично със съответния знак.

Същото важи за настройките за формат на дата, час и валута от локала. Кодът на формат в Basic ще бъде интерпретиран и изписан според настройките на локала.

### Пример:

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

## GetDefaultContext

Връща подразбирания контекст на фабриката за услуги на процеса, ако съществува, и null в противен случай.

GetDefaultContext е алтернатива на метода getComponentContext(), достъпен от глобалната променлива XSCRIPTCONTEXT или модула uno.py.

### Синтаксис:

svc.GetDefaultContext(): uno

### Резултат:

Когато се получават екземпляри на услуги от XMultiServiceFactory, се използва подразбираният контекст на компонент. За повече информация вижте главата Professional UNO в ръководството за разработчици (Developer’s Guide) на адрес api.libreoffice.org (на английски).

### Пример:

        ctx = bas.GetDefaultContext()

## GetGuiType

Връща числова стойност, която показва вида на графичния потребителски интерфейс. Тази функция се предлага само за съвместимост назад с предишни версии.

Вижте метода system() от модула platform на Python, ако искате да идентифицирате операционната система.

### Синтаксис:

svc.GetGuiType(): int

### Пример:

        n = bas.GetGuiType()

## GetPathSeparator

Връща зависимия от системата разделител за директории, с чиято помощ се задават файлови пътища.

Използвайте os.pathsep от модула os на Python, за да установите какъв е разделителят за пътища.

### Синтаксис:

svc.GetPathSeparator(): str

### Пример:

        sep = bas.GetPathSeparator()

## GetSystemTicks

Връща броя системни тактове, предоставен от операционната система. С помощта на тази функция можете да оптимизирате определени процеси. Използвайте този метод, за да оценявате време в милисекунди:

### Синтаксис:

svc.GetSystemTicks(): int

### Пример:

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

## GlobalScope.BasicLibraries

Връща UNO обекта, съдържащ всички споделени библиотеки и модули на Basic.

Този метод е еквивалентът в Python на GlobalScope.BasicLibraries в скриптовете на Basic.

### Синтаксис:

svc.GlobalScope.BasicLibraries(): uno

### Резултат:

com.sun.star.script.XLibraryContainer

### Пример:

Следващият пример зарежда библиотеката на Basic Gimmicks, ако все още не е заредена.

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

## GlobalScope.DialogLibraries

Връща UNO обекта, съдържащ всички споделени библиотеки с диалози.

Този метод е еквивалентът в Python на GlobalScope.DialogLibraries в скриптовете на Basic.

### Синтаксис:

svc.GlobalScope.DialogLibraries(): uno

### Резултат:

com.sun.star.comp.sfx2.DialogLibraryContainer

### Пример:

Следващият пример показва диалогов прозорец за съобщение с имената на всички налични библиотеки с диалози.

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

## InputBox

### Синтаксис:

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

### Параметри:

prompt: низов израз, показван като съобщение в диалоговия прозорец.

title: низов израз, показван в заглавната лента на диалоговия прозорец.

default: низов израз, показван в текстовото поле като подразбирана стойност, ако не е въведено друго.

xpostwips: целочислен израз, който задава хоризонталната позиция на диалоговия прозорец. Позицията представлява абсолютна координата и не е относителна спрямо прозореца на LibreOffice.

ypostwips: целочислен израз, който задава вертикалната позиция на диалоговия прозорец. Позицията представлява абсолютна координата и не е относителна спрямо прозореца на LibreOffice.

Ако xpostwips и ypostwips са пропуснати, диалоговият прозорец се центрира върху екрана. Позицията се задава в туипове.

### Резултат:

String

### Пример:

        txt = s.InputBox('Моля, въведете фраза:', "Драги потребителю")
        s.MsgBox(txt, s.MB_ICONINFORMATION, "Потвърждение на фразата")

За подробна информация, моля, вижте Input/Output to Screen with Python в уикито (на английски).

## MsgBox

Показва диалогов прозорец, който съдържа съобщение, и връща стойност по желание.
Константите MB_xx ви помагат да изберете типа на диалога, броя и типа на показваните бутони и типа на иконата. Чрез събирането на съответните им стойности се формират шаблони от битове, които определят облика на диалога на MsgBox.

### Синтаксис:

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

### Параметри:

prompt: израз – низ, показван като като съобщение в диалоговия прозорец. За преминаване на нов ред може да се използва Chr$(13).

title: израз от тип низ, показван в заглавната лента на диалоговия прозорец. Ако бъде пропуснат, в заглавната лента се изписва името на съответното приложение.

buttons: произволен израз от тип цяло число, който задава типа на диалоговия прозорец, броя и вида на показваните бутони и вида на иконата. buttons представлява комбинация от битови маски, т.е. от елементи, които могат да бъдат включени чрез прибавяне на съответните им стойности:

### Резултат:

Незадължително цяло число, както е описано по-горе за свойствата IDxx.

### Пример:

        txt = s.InputBox('Моля, въведете фраза:', "Драги потребителю")
        s.MsgBox(txt, s.MB_ICONINFORMATION, "Потвърждение на фразата")

За подробна информация, моля, вижте Input/Output to Screen with Python в уикито (на английски).

## Now

Връща текущата системна дата и час като вътрешен обект datetime.datetime на Python.

### Синтаксис:

svc.Now(): datetime

### Пример:

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

## RGB

Връща целочислена стойност за цвят, съставена от червен, зелен и син компонент.

### Синтаксис:

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

### Параметри:

red: целочислен израз, представящ червения компонент (0 – 255) на съставния цвят.

green: целочислен израз, представящ зеления компонент (0 – 255) на съставния цвят.

blue: целочислен израз, представящ синия компонент (0 – 255) на съставния цвят.

Резултатната стойност от тип Long се изчислява по следната формула:
Резултат = червено × 65 536 + зелено × 256 + синьо.

В режим на съвместимост с VBA (Option VBASupport 1) стойността от тип Long се изчислява като
Резултат = червено + зелено × 256 + синьо × 65 536.
Вижте Функция RGB [VBA].

Диалогът за избор на цвят помага за изчисляване на червения, зеления и синия компонент на композитен цвят. Диалоговият прозорец за избор на цвят се показва, когато сменяте цвета на текста и изберете Цвят по избор.

### Резултат:

Integer

### Пример:

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

## Xray

Инспектиране на UNO обекти или променливи.

### Синтаксис:

svc.Xray(obj: any)

### Параметри:

obj: променлива или UNO обект.

### Пример:

        bas.Xray(bas.StarDesktop)

В ScriptForge всички подпрограми или идентификатори на Basic с префикс „_“ са запазени за вътрешна употреба. Те не са предназначени за използване в макроси на Basic.

Теми, свързани с показаната

Спецификатор GlobalScope

Програмиране със скриптове на Python

uno.fileUrlToSystemPath()

uno.systemPathToFileUrl()

Input/Output to Screen with Python в уикито (на английски)

XSCRIPTCONTEXT.getComponentContext()

uno.getComponentContext()

platform.system()

os.pathsep()