Услуга ScriptForge.Basic

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

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


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

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


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

note

Преди да използвате услугата 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
обект

Returns the StarDesktop object that represents the LibreOffice application.

ThisComponent

Yes

UNO
object

If the current component refers to a LibreOffice document, this method returns the UNO object representing the document. This property returns None when the current component does not correspond to a document.

ThisDatabaseDocument

Yes

UNO
object

If the script is being executed from a Base document or any of its subcomponents this method returns the main component of the Base instance. This property returns None otherwise.


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

note

Този метод излага вградената функция на 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)
  

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.

note

Низът, подаван към DateValue, трябва да е в някой от форматите, дефинирани от настройката за локал (вижте - Езици и локали - Общи) или във формата за дати на 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, може да се задава в - Езици и локали - Общи. Във форматиращите кодове на 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, "Потвърждение на фразата")
  
note

За подробна информация, моля, вижте 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, "Потвърждение на фразата")
  
note

За подробна информация, моля, вижте 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 + синьо.

warning

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


tip

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


Резултат:

Integer

Пример:


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

Xray

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

Синтаксис:

svc.Xray(obj: any)

Параметри:

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

Пример:


    bas.Xray(bas.StarDesktop)
  
warning

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


Моля, подкрепете ни!