Услуга 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

Python alternatives exist for methods marked with (*).

CDate

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

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

Синтаксис:

svc.CDate(expression: any): obj

Параметри:

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

Когато преобразувате низов израз, датата и часът трябва да съответстват или на някой от шаблоните за разпознаване, дефинирани в настройката за локал (вижте - Езици и локали - Общи), или на формат на 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)

uno module fileUrlToSystemPath() method returns a system path using an identical syntax.


    import uno
    filename = uno.fileUrlToSystemPath( "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)

uno module systemPathToFileUrl() method returns a file URL for the given system path.


    from uno import systemPathToFileUrl as ConvertToUrl
    filename = ConvertToUrl( 'C:\Program Files(x86)\LibreOffice\News.txt' )
    bas.MsgBox(filename)

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

uno module createUnoStruct() method creates an instance of a Uno structure type.


    import uno
    p = uno.createUnoStruct( 'com.sun.star.beans.Property' )
    bas.MsgBox(p)

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, трябва да е в някой от форматите, дефинирани от настройката за локал (вижте - Езици и локали - Общи) или във формата за дати на ISO "yyyy-mm-dd" (година, месец и ден, разделени с късо тире).

Тип на резултата:

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

Пример:


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

Format

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

Синтаксис:

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

Параметри:

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

format: String that specifies the format code for the number. If format is omitted, the Format function works like the LibreOffice Basic Str() function.

Тип на резултата:

Текстов низ.

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

In BASIC, a format code can be divided into three sections that are separated by semicolons. The first part defines the format for positive values, the second part for negative values, and the third part for zero. If you only specify one format code, it applies to all numbers.

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

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

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

Code	Description
0	If expression has a digit at the position of the 0 in the format code, the digit is displayed, otherwise a zero is displayed. Ако expression съдържа по-малко цифри от броя нули в кода format (в цялата и/или дробната част), се показват водещи или завършващи нули. Ако expression съдържа повече цифри в цялата си част, отколкото са нулите в кода format, допълнителните цифри се показват без форматиране. Дробната част в expression се закръглява според броя нули вдясно от десетичния разделител в кода format.
#	If expression contains a digit at the position of the # placeholder in the format code, the digit is displayed, otherwise nothing is displayed at this position. Този знак работи като 0, но ако знаците # в кода format са повече от цифрите в expression, не се показват водещи или завършващи нули. Изписват се само значещите цифри от expression.
. (period)	The decimal placeholder determines the number of decimal places to the left and right of the decimal separator. Ако кодът format съдържа само знаци # вляво от този символ, числата, по-малки от 1, започват с десетичен разделител. За да се показва винаги 0 в началото на дробни числа, използвайте 0 като запазено място за първата цифра вляво от десетичния разделител. Употребата на точка като разделител на хилядите или на дробната част зависи от регионалните настройки. Когато въвеждате число направо в кода на Basic, винаги използвайте точка за разделител на дробната част. Знакът, който се показва на екрана като десетичен разделител, зависи от формата за числа в системните настройки.
%	Multiplies the expressionby 100 and inserts the percent sign (%) where the expression appears in the format code.
E- E+ e- e+	If the format code contains at least one digit placeholder (0 or #) to the right of the symbol E-, E+, e-, or e+, the expression is formatted in the scientific or exponential format. The letter E or e is inserted between the number and the exponent. The number of placeholders for digits to the right of the symbol determines the number of digits in the exponent. Ако експонентата е отрицателна, точно преди нея се показва минус при E-, E+, e- и e+. Ако експонентата е положителна, при нея се показва знак плюс само при E+ или e+.
- + $ ( ) space	: A plus (+), minus (-), dollar ($), space, or brackets entered directly in the format code is displayed as a literal character.
\	За да включите други знаци освен изброените, трябва да поставите пред тях обратна наклонена черта (\) или да ги оградите с кавички (" "). The backslash displays the next character in the format code. Знаците в кода format, които имат специално значение, могат да се показват буквално само ако са предшествани от обратна наклонена черта. Самата тя не се показва, освен ако я въведете два пъти във форматиращия код (\\). Знаците, пред които трябва да има обратно наклонена черта във форматиращия код, за да се покажат буквално, са тези за форматиране на дати и часове (a, c, d, h, m, n, p, q, s, t, w, y, /, :), за форматиране на числа (#, 0, %, E, e, запетая, точка) и за форматиране на низове (@, &, <, >, !).

Predefined formats

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

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

Code	Description
"<"	Convert expression to lower case
">"	Convert expression to upper case.
"c" or "General Date"	Returns the numeric expression in short date format, optionally with "H:MM:SS AM/PM". If expression is a string, returns the string.
"n"	Returns the minute of the numeric expression, with 1 or 2 digits.
"nn"	Returns the minute of the numeric expression with two digits.
"w"	Returns the week day of the numeric expression. 1 is Sunday and 7 is Saturday.
"General Number"	Returns the numeric expression with 12 digits (0.############).
"Currency"	Returns the numeric expression in the currency of the locale.
"Fixed"	Returns the numeric expression with 2 decimal places (0.00).
"Standard"	Returns the numeric expression with thousands separators and 2 decimals (@0.00).
"Percent"	Returns the numeric expression as percent value (0.00%).
"Scientific"	Returns the numeric expression in scientific notation (#.00E+00);
"Yes/No"	Returns "Yes" if the numeric expression is not equal to zero, "No" otherwise. "Yes" and "No" are localized.
"True/False"	Returns "True" if the numeric expression is not equal to zero, "False" otherwise. "True" and "False" are localized.
"On/Off"	Returns "On" if the numeric expression is not equal to zero, "Off" otherwise. "On" and "Off" are localized.
"Long Date" or "dddddd"	Returns the numeric expression in system long date format, and depends on the locale.
"Medium Date"	Returns the numeric expression in date format DD-MMM-YY, and depends on the locale.
"Short Date" or "ddddd"	Returns the numeric expression in system short date format, and depends on the locale.
"Long Time" or "ttttt"	Returns the numeric expression in system long time format, and depends on the locale("H:MM:SS AM/PM").
"Medium Time"	Returns the numeric expression in system medium time format, and depends on the locale (HH:MM AM/PM)
"Short Time"	Returns the numeric expression in system short time format, and depends on the locale (HH:MM).

Пример:


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

Wiser script instructions are available from Identifying the operating system help page.

• ScriptForge.Platform service provides a collection of properties about the current execution environment and context, that include platform detection.

• Extensive operating system name identification is available from INFO("system") Calc formula.

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