Съдържание
Индекс 🔎︎

# 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.

Typical example:

       bas.MsgBox('Display this text in a message box from a Python script')

ScriptForge.Basic service is limited to Python scripts.

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

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

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

## Свойства

Име | ReadOnly | Тип | Описание
--- | --- | --- | ---
MB_OK, MB_OKCANCEL, MB_RETRYCANCEL, MB_YESNO, MB_YESNOCANCEL | Да | Integer | Values: 0, 1, 5, 4, 3
MB_ICONEXCLAMATION, MB_ICONINFORMATION, MB_ICONQUESTION, MB_ICONSTOP | Да | Integer | Values: 48, 64, 32, 16
MB_ABORTRETRYIGNORE, MB_DEFBUTTON1, MB_DEFBUTTON2, MB_DEFBUTTON3 | Да | Integer | Values: 2, 128, 256, 512
IDABORT, IDCANCEL, IDIGNORE, IDNO, IDOK, IDRETRY, IDYES | Да | Integer | Values: 3, 2, 5, 7, 1, 4, 6 Constants indicating MsgBox selected button.
StarDesktop | Да | 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.

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.

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

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 = bas.CDateFromUnoDateTime(uno_date)
        bas.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 = bas.CDateToUnoDateTime(current_datetime)
        bas.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 = bas.ConvertFromUrl( "file:///C:/Program%20Files%20(x86)/LibreOffice/News.txt")
        bas.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 = bas.ConvertToUrl( 'C:\Program Files(x86)\LibreOffice\News.txt')
        bas.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 = bas.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 datetime.datetime value.

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

A datetime.datetime value.

### Пример:

        dt = datetime.datetime(2004, 1, 31)
        dt = bas.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 е първата седмица, съдържаща само дни от новата година.

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

Число.

### Пример:

        date1 = datetime.datetime(2005,1, 1)
        date2 = datetime.datetime(2005,12,31)
        diffDays = bas.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(bas.DatePart("ww", datetime.datetime(2005,12,31)
        print(bas.DatePart('q', datetime.datetime(1999,12,30)

## DateValue

Computes a date value from a date string.

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

svc.DateValue(date: str): datetime

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

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

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

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

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

### Пример:

        dt = bas.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().

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

Текстов низ.

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

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

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

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

### Пример:

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

## GetDefaultContext

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

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 = bas.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 = bas.GetGuiType()

## GetPathSeparator

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

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

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

svc.GetPathSeparator(): str

### Пример:

        sep = bas.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 = bas.GetSystemTicks()
        time.sleep(1)
        ticks_end = bas.GetSystemTicks()
        bas.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 = bas.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 = 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('Please enter a phrase:', "Dear user")
        s.MsgBox(txt, s.MB_ICONINFORMATION, "Confirmation of phrase")

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.

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

bas.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, s.MB_ICONINFORMATION, "Confirmation of phrase")

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

### Пример:

        bas.MsgBox(bas.Now(), bas.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) на съставния цвят.

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

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

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

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

Integer

### Пример:

        YELLOW = bas.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 = bas.ThisComponent
        bas.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 = bas.ThisDatabaseDocument
        table_names = db_doc.DataSource.getTables().getElementNames()
        bas.MsgBox("\n".join(table_names))

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.

### Пример:

        bas.Xray(bas.StarDesktop)

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

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

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

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

uno.fileUrlToSystemPath()

uno.systemPathToFileUrl()

Input/Output to Screen with Python on the wiki

XSCRIPTCONTEXT.getComponentContext()

uno.getComponentContext()

platform.system()

os.pathsep()