ScriptForge.Basic service

The ScriptForge.Basic service proposes a collection of LibreOffice Basic methods to be executed in a Python context. Basic service methods reproduce the exact syntax and behaviour of Basic builtin functions.

note

Тази услуга е налична от LibreOffice 7.2 нататък.


Typical example:


   svc.MsgBox('This has to be displayed in a message box')
  
warning

ScriptForge.Basic service is limited to Python scripts.


Service invocation

Before using the Basic service, import the CreateScriptService() method from the scriptforge module:


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

Properties

Name

ReadOnly

Type

Description

MB_OK, MB_OKCANCEL, MB_RETRYCANCEL, MB_YESNO, MB_YESNOCANCEL

Yes

integer

Values: 0, 1, 5, 4, 3

MB_ICONEXCLAMATION, MB_ICONINFORMATION, MB_ICONQUESTION, MB_ICONSTOP

Yes

integer

Values: 48, 64, 32, 16

MB_ABORTRETRYIGNORE, MB_DEFBUTTON1, MB_DEFBUTTON2, MB_DEFBUTTON3

Yes

integer

Values: 2, 128, 256, 512

IDABORT, IDCANCEL, IDIGNORE, IDNO, IDOK, IDRETRY, IDYES

Yes

integer

Values: 3, 2, 5, 7, 1, 4, 6
Constants indicating MsgBox selected button.

StarDesktop

Yes

UNO
object

StarDesktop object represents LibreOffice Start Center.


List of Methods in the Basic Service

CDate
CDateFromUnoDateTime
CDateToUnoDateTime
ConvertFromUrl
ConvertToUrl
CreateUnoService
DateAdd
DateDiff
DatePart

DateValue
Format
GetDefaultContext
GetGuiType
GetPathSeparator
GetSystemTicks
GlobalScope.BasicLibraries
GlobalScope.DialogLibraries
InputBox

MsgBox
Now
RGB
ThisComponent
ThisDatabaseDocument
Xray




CDate

Converts a numeric expression or a string to a datetime.datetime Python native object.

note

This method exposes the Basic builtin function CDate to Python scripts.


Синтаксис:

svc.CDate(expression: any): obj

Параметри:

expression: a numeric expression or a string representing a date.

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

Пример:


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

CDateFromUnoDateTime

Converts a UNO date/time representation to a datetime.datetime Python native object.

Синтаксис:

svc.CDateFromUnoDateTime(unodate: uno): obj

Параметри:

unodate: A UNO date/time object of one of the following types: com.sun.star.util.DateTime, com.sun.star.util.Date or com.sun.star.util.Time

Пример:

The following example creates a com.sun.star.util.DateTime object and converts it to a datetime.datetime Python object.


    import uno
    uno_date = uno.createUnoStruct('com.sun.star.util.DateTime')
    uno_date.Year = 1983
    uno_date.Month = 2
    uno_date.Day = 23
    new_date = svc.CDateFromUnoDateTime(uno_date)
    svc.MsgBox(str(new_date)) # 1983-02-23 00:00:00
  

CDateToUnoDateTime

Converts a date representation into a com.sun.star.util.DateTime object.

Синтаксис:

svc.CDateToUnoDateTime(date: obj): uno

Параметри:

date: A Python date/time object of one of the following types: datetime.datetime, datetime.date, datetime.time, float (time.time) or time.struct_time.

Пример:


    from datetime import datetime
    current_datetime = datetime.now()
    uno_date = svc.CDateToUnoDateTime(current_datetime)
    svc.MsgBox(str(uno_date.Year) + "-" + str(uno_date.Month) + "-" + str(uno_date.Day))
  

ConvertFromUrl

Returns a system path file name for the given file: URL.

Синтаксис:

svc.ConvertFromUrl(url: str): str

Параметри:

url: An absolute file: URL.

Резултат:

A system path file name.

Пример:


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

ConvertToUrl

Returns a file: URL for the given system path.

Синтаксис:

svc.ConvertToUrl(systempath: str): str

Параметри:

systempath: A system file name as a string.

Резултат:

A file: URL as a string.

Пример:


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

CreateUnoService

Instantiates a UNO service with the ProcessServiceManager.

Синтаксис:

svc.CreateUnoService(servicename: str): uno

Параметри:

servicename : A fully qualified service name such as "com.sun.star.ui.dialogs.FilePicker" or 'com.sun.star.sheet.FunctionAccess'.

Пример:


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

DateAdd

Adds a date or time interval to a given date/time a number of times and returns the resulting date.

Синтаксис:

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

Параметри:

interval: A string expression from the following table, specifying the date or time interval.

interval (низова стойност)

Обяснение

yyyy

Година

q

Тримесечие

m

Месец

y

Ден от годината

w

Ден от седмицата

ww

Седмица от годината

d

Ден

h

Час

n

Минута

s

Секунда


number: A numerical expression specifying how often the interval value will be added when positive or subtracted when negative.

date: A given datetime.datetime value, the interval value will be added number times to this date/time value.

Резултат:

A datetime.datetime value.

Пример:


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

DateDiff

Returns the number of date or time intervals between two given date/time values.

Синтаксис:

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

Параметри:

interval: A string expression specifying the date interval, as detailed in above DateAdd method.

date1, date2: The two datetime.datetime values to be compared.

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

Стойност на firstdayofweek

Обяснение

0

Използване на системните настройки

1

Неделя (по подразбиране)

2

Понеделник

3

Вторник

4

Сряда

5

Четвъртък

6

Петък

7

Събота


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

Стойност на firstweekofyear

Обяснение

0

Използване на системните настройки

1

Седмица 1 е седмицата, съдъжаща 1 януари (по подразбиране).

2

Седмица 1 е първата седмица, съдържаща четири или повече дни от съответната година.

3

Седмица 1 е първата седмица, съдържаща само дни от новата година.


Резултат:

A number.

Пример:


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

DatePart

The DatePart function returns a specified part of a date.

Синтаксис:

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

Параметри:

interval: A string expression specifying the date interval, as detailed in above DateAdd method.

date: The date/time from which the result is calculated.

firstdayofweek, firstweekofyear: optional parameters that respectively specify the starting day of a week and the starting week of a year, as detailed in above DateDiff method.

Резултат:

The extracted part for the given date/time.

Пример:


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

DateValue

Computes a date value from a date string.

Синтаксис:

svc.DateValue(date: str): datetime

Параметри:

Date: Низов израз, съдържащ датата за изчислението. За разлика от функцията DateSerial, при която годините, месеците и дните се предават като отделни числови стойности, за DateValue низът с датата трябва или да съответства или на някой от шаблоните за разпознаване на дати, дефинирани в настройката за локал (вижте - Езикови настройки - Езици), или на формат за дати на ISO (в момента се приема само форматът с тиретата, например "2012-12-31").

Резултат:

The computed date.

Пример:


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

Format

Converts a number to a string, and then formats it according to the format that you specify.

Синтаксис:

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

Параметри:

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

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

Резултат:

Текстов низ.

Formatting Codes

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

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“ всички те връщат десетично число с две дробни позиции.

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

Predefined Formats

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

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

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

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

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

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

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

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

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

Пример:


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

GetDefaultContext

Returns the default context of the process service factory, if existent, else returns a null reference.

GetDefaultContext is an alternative to the getComponentContext() method available from XSCRIPTCONTEXT global variable or from uno.py module.

Синтаксис:

svc.GetDefaultContext(): uno

Резултат:

The default component context is used, when instantiating services via XMultiServiceFactory. See the Professional UNO chapter in the Developer's Guide on api.libreoffice.org for more information.

Пример:


    ctx = svc.GetDefaultContext()
  

GetGuiType

Returns a numerical value that specifies the graphical user interface. This function is only provided for backward compatibility with previous versions.

Refer to system() method from platform Python module to identify the operating system.

Синтаксис:

svc.GetGuiType(): int

Пример:


    n = svc.GetGuiType()
  

GetPathSeparator

Returns the operating system-dependent directory separator used to specify file paths.

Use os.pathsep from os Python module to identify the path separator.

Синтаксис:

svc.GetPathSeparator(): str


    svc.GetPathSeparator(): str
  

Пример:


    sep = svc.GetPathSeparator()
  

GetSystemTicks

Returns the number of system ticks provided by the operating system. You can use this function to optimize certain processes. Use this method to estimate time in milliseconds:

Синтаксис:

svc.GetSystemTicks(): int

Пример:


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

GlobalScope.BasicLibraries

Returns the UNO object containing all shared Basic libraries and modules.

This method is the Python equivalent to GlobalScope.BasicLibraries in Basic scripts.

Синтаксис:

svc.GlobalScope.BasicLibraries(): uno

Резултат:

com.sun.star.script.XLibraryContainer

Пример:

The following example loads the Gimmicks Basic library if it has not been loaded yet.


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

GlobalScope.DialogLibraries

Returns the UNO object containing all shared dialog libraries.

This method is the Python equivalent to GlobalScope.DialogLibraries in Basic scripts.

Синтаксис:

svc.GlobalScope.DialogLibraries(): uno

Резултат:

com.sun.star.comp.sfx2.DialogLibraryContainer

Пример:

The following example shows a message box with the names of all available dialog libraries.


    dlg_libs = svc.GlobalScope.DialogLibraries()
    lib_names = dlg_libs.getElementNames()
    svc.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('Please enter a phrase:', "Dear user")
    s.MsgBox(txt, MB_ICONINFORMATION, "Confirmation of phrase")
  
note

For in-depth information please refer to Input/Output to Screen with Python on the Wiki.


MsgBox

Displays a dialog box containing a message and returns an optional value.
MB_xx constants help specify the dialog type, the number and type of buttons to display, plus the icon type. By adding their respective values they form bit patterns, that define the MsgBox dialog appearance.

Синтаксис:

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

Параметри:

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

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

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

Резултат:

An optional integer as detailed in above IDxx properties.

Пример:


    txt = s.InputBox('Please enter a phrase:', "Dear user")
    s.MsgBox(txt, MB_ICONINFORMATION, "Confirmation of phrase")
  
note

For in-depth information please refer to Input/Output to Screen with Python on the Wiki.


Now

Returns the current system date and time as a datetime.datetime Python native object.

Синтаксис:

svc.Now(): datetime

Пример:


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

RGB

Returns an integer color value consisting of red, green, and blue components.

Синтаксис:

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

Параметри:

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

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

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

tip

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


Резултат:

integer

Пример:


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

ThisComponent

If the current component refers to a LibreOffice document, this method returns the UNO object representing the document.

The method will return None when the current component does not correspond to a document.

Синтаксис:

svc.ThisComponent(): uno

Пример:


    comp = svc.ThisComponent
    svc.MsgBox("\n".join(comp.getSupportedServiceNames()))
  

ThisDatabaseDocument

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 method returns None otherwise.

Синтаксис:

svc.ThisDatabaseDocument(): uno

Пример:


    db_doc = svc.ThisDatabaseDocument
    table_names = db_doc.DataSource.getTables().getElementNames()
    bas.MsgBox("\n".join(table_names))
  
tip

Visit the OfficeDatabaseDocument API page to learn more about Base's main component structure.


Xray

Inspect Uno objects or variables.

Синтаксис:

svc.Xray(obj: any)

Параметри:

obj: A variable or Uno object.

Пример:


    svc.Xray(svc.StarDesktop)
  
warning

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


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