Słužba ScriptForge.Basic

Słužba ScriptForge.Basic zběrku metodow LibreOffice Basic namjetuje, kotrež so maja w konteksće Python wuwjesć. Metody słužby Basic eksaktnu syntaksu a zadźerženje zatwarjenych funkcijow Basic reprodukuja.

Typiski přikład:


   bas.MsgBox('Tutón tekst w zdźělenskim dialogu ze skripta Python pokazać')

Słužba ScriptForge.Basic je na skripty Python wobmjezowana.

Wuwołanje słužby

Prjedy hač słužbu Basic wužiwaće, importujće metodu CreateScriptService() z modula scriptforge:


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

Kajkosće

Mjeno	Přećiwo pisanju škitany	Typ	Wopisanje
MB_OK, MB_OKCANCEL, MB_RETRYCANCEL, MB_YESNO, MB_YESNOCANCEL	Haj	Integer	Hódnoty: 0, 1, 5,4, 3
MB_ICONEXCLAMATION, MB_ICONINFORMATION, MB_ICONQUESTION, MB_ICONSTOP	Haj	Integer	Hódnoty: 48, 64, 32, 16
MB_ABORTRETRYIGNORE, MB_DEFBUTTON1, MB_DEFBUTTON2, MB_DEFBUTTON3	Haj	Integer	Hódnoty: 2, 128, 256, 512
IDABORT, IDCANCEL, IDIGNORE, IDNO, IDOK, IDRETRY, IDYES	Haj	Integer	Hódnoty: 3, 2, 5, 7, 1, 4 Konstanty, kotrež wubrane tłóčatko MsgBox pokazuje.
StarDesktop	Haj	Objekt UNO	Wróći objekt StarDesktop, kotryž nałoženje LibreOffice reprezentuje.
ThisComponent	Haj	Objekt UNO	Jeli aktualna komponenta so na dokument LibreOffice poćahuje, tuta metoda objekt UNO wróći, kotryž dokument reprezentuje. Tuta kajkosć None wróći, hdyž aktualna komponenta dokumentej njewotpowěduje.
ThisDatabaseDocument	Haj	Objekt UNO	Jeli skript so z dokumenta Base abo z jedneje jeho poddokumentow wuwjedźe, tuta metoda hłownu komponentu instancy Base wróći. Tuta kajkosć hewak None wróći.

Lisćina metodow w słužbje Base
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

Alternatiwy Python za metody eksistuja, kotrež su z (*) markěrowane.

CDate

Přetworja numeriski wuraz abo znamješkowy rjećazk do natiwneho objekta Python datetime.datetime.

Tuta metoda skriptam Python zatwarjenu funkciju Basic CDate k dispoziciji staja.

Syntaksa:

svc.CDate(expression: any): obj

Parametry:

expression: numeriski wuraz abo znamješkowy rjećazk, kotryž datum reprezentuje.

When you convert a string expression, the date and time must be entered either in one of the date acceptance patterns defined for your locale setting (see - Languages and Locales - General) or in ISO date format (momentarily, only the ISO format with hyphens, e.g. "2012-12-31" is accepted). In numeric expressions, values to the left of the decimal represent the date, beginning from December 31, 1899. Values to the right of the decimal represent the time.

Přikład:


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

CDateFromUnoDateTime

Přetworja reprezentaciju datum/čas UNO do natiwneho objekta Python datetime.datetime.

Syntaksa:

svc.CDateFromUnoDateTime(unodate: uno): obj

Parametry:

unodate: Objekt datum/čas UNO jednoho ze slědowacych typow: com.sun.star.util.DateTime, com.sun.star.util.Date abo com.sun.star.util.Time

Přikład:

Slědowacy přikład com.sun.star.util.DateTime wutworja a přetworja jón do objekta Python datetime.datetime.


    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

Přetworja datumowu reprezentaciju do objekta com.sun.star.util.DateTime.

Syntaksa:

svc.CDateToUnoDateTime(date: obj): uno

Parametry:

date: Objekt datum/čas Python jednoho ze slědowacych typow: datetime.datetime, datetime.date, datetime.time, float (time.time) abo time.struct_time.

Přikład:


    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

Wróći datajowe mjeno systemoweje šćežki za daty URL file:.

Syntaksa:

svc.ConvertFromUrl(url: str): str

Parametry:

url: Absolutny URL file:.

Typ wróćenja:

Datajowe mjeno systemoweje šćežki.

Přikład:


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

Metoda uno module fileUrlToSystemPath() systemowu šćežku z pomocu identiskeje syntaksy wróći.


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

ConvertToUrl

Wróći URL file: za datu systemowu šćežku.

Syntaksa:

svc.ConvertToUrl(systempath: str): str

Parametry:

systempath: Systemowe datajowe mjeno jako znamješkowy rjećazk.

Typ wróćenja:

URL file: jako znamješkowy rjećazk.

Přikład:


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

Metoda uno module systemPathToFileUrl() datajowy URL za datu systemowu šćežku wróći.


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

CreateUnoService

Instancuje słužbu UNO z ProcessServiceManager.

Syntaksa:

svc.CreateUnoService(servicename: str): uno

Parametry:

servicename: Połnje kwalifikowane słužbowe mjeno kaž com.sun.star.ui.dialogs.FilePicker abo com.sun.star.sheet.FunctionAccess.

Přikład:


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

CreateUnoStruct

Wróći instancu struktury UNO podateho typa.

Syntaksa:

svc.CreateUnoStruct(unostructure: str): uno

Parametry:

unostructure: Połnje kwalifikowane strukturowe mjeno kaž com.sun.star.beans.Property abo com.sun.star.util.DateTime.

Přikład:


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

Metoda uno module createUnoStruct() instancu strukturoweho typa Uno wutwori.


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

DateAdd

Přidawa wjacekróć datemu datumej/časej datum abo časowy interwal a wróći rezultowacy datum.

Syntaksa:

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

Parametry:

interval: Znamješkowy rjećazk ze slědowaceje tabele, kotryž datum abo časowy interwal podawa.

interval (string value)	Explanation
yyyy	Year
q	Quarter
m	Month
y	Day of year
w	Weekday
ww	Week of year
d	Day
h	Hour
n	Minute
s	Second

number: Numeriski wuraz, kotryž podawa, kak husto so hódnota interval přidawa, hdyž je pozitiwny abu subtrahuje, hdyž je negatiwny.

date: Data hódnota datetime.datetime, hódnota interval so number-króć tutej hódnoće datetime.datetime přidawa.

Typ wróćenja:

Hódnota datetime.datetime.

Přikład:


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

DateDiff

Wróći ličbu datumowych abo časowych interwalow mjez dwěmaj datymaj datumowymaj/časowymaj hódnotomaj.

Syntaksa:

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

Parametry:

interval: Znamješkowy rjećazk, kotryž datumowy interwal pdoawa, kaž w metodźe DateAdd horjeka wopisane.

date1, date2: Dwě hódnoće datetime.datetime, kotrejž so matej přirunać.

firstdayofweek: An optional parameter that specifies the starting day of a week.

firstdayofweek value	Explanation
0	Use system default value
1	Sunday (default)
2	Monday
3	Tuesday
4	Wednesday
5	Thursday
6	Friday
7	Saturday

firstweekofyear: An optional parameter that specifies the starting week of a year.

firstweekofyear value	Explanation
0	Use system default value
1	Week 1 is the week with January, 1st (default)
2	Week 1 is the first week containing four or more days of that year
3	Week 1 is the first week containing only days of the new year

Typ wróćenja:

Ličba.

Přikład:


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

DatePart

Funkcija DatePart wěsty dźěl datuma wróći.

Syntaksa:

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

Parametry:

interval: Znamješkowy rjećazk, kotryž datumowy interwal podawa, kaž w metodźe DateAdd horjeka wopisane.

date: Datum/čas, wot kotrehož so wuslědk wuličuje.

firstdayofweek, firstweekofyear: opcionalne parametry, kotrež kóždy startowy dźeń tydźenja a startowy tydźeń lěta postajenja, kaž horjeka w metodźe DateDiff wopisane.

Typ wróćenja:

Ekstrahowany dźěl za daty datum/čas.

Přikład:


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

DateValue

Wobličuje datumowu hódnotu z datumoweho znamješkoweho rjećazka.

Syntaksa:

svc.DateValue(date: str): datetime

Parametry:

date: A string that contains the date that will be converted to a Date object.

The string passed to DateValue must be expressed in one of the date formats defined by your locale setting (see - Languages and Locales - General) or using the ISO date format "yyyy-mm-dd" (year, month and day separated by hyphens).

Typ wróćenja:

Wobličeny datum.

Přikład:


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

Format

Přetworja ličbu do znamješkoweho rjećazka a formatěruje jón potom po formaće, kotryž podawaće.

Syntaksa:

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

Parametry:

expression: Numeric expression that you want to convert to a formatted string.

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

Typ wróćenja:

Text string.

Formatting Codes

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.

You can set the locale used for controlling the formatting numbers, dates and currencies in LibreOffice Basic in - Languages and Locales - General. In Basic format codes, the decimal point (.) is always used as placeholder for the decimal separator defined in your locale and will be replaced by the corresponding character.

The same applies to the locale settings for date, time and currency formats. The Basic format code will be interpreted and displayed according to your locale setting.

The following list describes the codes that you can use for formatting a numeric expression:

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. If expression has fewer digits than the number of zeros in the format code, (on either side of the decimal), leading or trailing zeros are displayed. If the expression has more digits to the left of the decimal separator than the amount of zeros in the format code, the additional digits are displayed without formatting. Decimal places in the expression are rounded according to the number of zeros that appear after the decimal separator in the format code.
#	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. This symbol works like the 0, except that leading or trailing zeroes are not displayed if there are more # characters in the format code than digits in the expression. Only the relevant digits of the expression are displayed.
. (period)	The decimal placeholder determines the number of decimal places to the left and right of the decimal separator. If the format code contains only # placeholders to the left of this symbol, numbers less than 1 begin with a decimal separator. To always display a leading zero with fractional numbers, use 0 as a placeholder for the first digit to the left of the decimal separator. The use of a period as a thousands and decimal separator is dependent on the regional setting. When you enter a number directly in Basic source code, always use a period as decimal delimiter. The actual character displayed as a decimal separator depends on the number format in your system settings.
%	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. If the exponent is negative, a minus sign is displayed directly before an exponent with E-, E+, e-, e+. If the exponent is positive, a plus sign is only displayed before exponents with E+ or e+.
- + $ ( ) space	: A plus (+), minus (-), dollar ($), space, or brackets entered directly in the format code is displayed as a literal character.
\	To display characters other than the ones listed here, you must precede it by a backslash (\), or enclose it in quotation marks (" "). The backslash displays the next character in the format code. Characters in the format code that have a special meaning can only be displayed as literal characters if they are preceded by a backslash. The backslash itself is not displayed, unless you enter a double backslash (\\) in the format code. Characters that must be preceded by a backslash in the format code in order to be displayed as literal characters are date- and time-formatting characters (a, c, d, h, m, n, p, q, s, t, w, y, /, :), numeric-formatting characters (#, 0, %, E, e, comma, period), and string-formatting characters (@, &, <, >, !).

Predefined formats

You can also use the following predefined number formats. Except for "General Number", all of the predefined format codes return the number as a decimal number with two decimal places.

If you use predefined formats, the name of the format must be enclosed in quotation marks.

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

The same applies to the locale settings for date, time and currency formats. The Basic format code will be interpreted and displayed according to your locale setting.

Přikład:


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

GetDefaultContext

Wróći standardny kontekst „Process Service Factory“, jeli eksistuje, hewak so nulowa referenca wróći.

GetDefaultContext je alternatiwa k metodźe getComponentContext(), kotraž je z globalneje wariable XSCRIPTCONTEXT abo z modula uno.py k dispoziciji.

Syntaksa:

svc.GetDefaultContext(): uno

Typ wróćenja:

Kontekst standardneje komponenty so wužiwa, hdyž so słužby XMultiServiceFactory instancuja. Hlejće kapitl Professional UNO w přiručnicy za wuwiwarjow na apo.libreoffice.org za dalše informacije.

Přikład:


    ctx = bas.GetDefaultContext()

GetGuiType

Wróći numerisku hódnotu, kotraž grafiski wužiwarski powjerch podawa. Tuta funkcija je jenož za kompatibelnosć dele z předchadnymi wersijemi k dispoziciji.

Wotkazuje na metodu system() z modula Python platform, zo by so dźěłowy system identifikował.

Syntaksa:

svc.GetGuiType(): int

Přikład:


    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

Wróći wot dźěłoweho systema wotwisne zapisowe dźělatko, kotrež so wužiwa, zo by datajowe šćežki podało.

Wužiwajće os.pathsep z modula Python os, zo byšće šćežkowe dźělatko identifikował.

Syntaksa:

svc.GetPathSeparator(): str

Přikład:


    sep = bas.GetPathSeparator()

GetSystemTicks

Wróći ličbu systemowych tikow, kotrež so přez dźěłowy system k dispoziciji stajeja. Móžeće tutu funkciju wužiwać, zo byšće wěste procesy optimował. Wužiwajće tutu metodu, zo byšće čas w milisekundach trochował:

Syntaksa:

svc.GetSystemTicks(): int

Přikład:


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

GlobalScope.BasicLibraries

Wróći objekt UNO, kotryž wšě zhromadnje wužite biblioteki a module Basic wobsahuje.

Tuta metoda je ekwiwalent Python k GlobalScope.BasicLibraries w skriptach Basic.

Syntaksa:

svc.GlobalScope.BasicLibraries(): uno

Typ wróćenja:

com.sun.star.script.XLibraryContainer

Přikład:

Slědowacy přikład biblioteku Basic Gimmicks začita, jeli hišće njeje začitana.


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

GlobalScope.DialogLibraries

Wróći objekt UNO, kotryž wšě zhromadnje wužite dialogowe biblioteki wobsahuje.

Tuta metoda je ekwiwalent Python k GlobalScope.DialogLibraries w skriptach Basic.

Syntaksa:

svc.GlobalScope.DialogLibraries(): uno

Typ wróćenja:

com.sun.star.comp.sfx2.DialogLibraryContainer

Přikład:

Slědowacy přikład zdźělenske polo z mjenami wšěch dialogowych bibliotekow pokazuje, kotrež su k dispoziciji.


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

InputBox

Syntaksa:

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

Parametry:

prompt: String expression displayed as the message in the dialog box.

title: String expression displayed in the title bar of the dialog box.

default: String expression displayed in the text box as default if no other input is given.

xpostwips: Integer expression that specifies the horizontal position of the dialog. The position is an absolute coordinate and does not refer to the window of LibreOffice.

ypostwips: Integer expression that specifies the vertical position of the dialog. The position is an absolute coordinate and does not refer to the window of LibreOffice.

If xpostwips and ypostwips are omitted, the dialog is centered on the screen. The position is specified in twips.

Typ wróćenja:

String

Přikład:


    txt = s.InputBox('Prošu zapodajće sadu:', "Waženy wužiwar")
    s.MsgBox(txt, s.MB_ICONINFORMATION, "Wobkrućenje sady")

Za podrobne informacije čitajće prošu Input/Output to Screen with Python we wikiju.

MsgBox

Pokazuje dialogowe polo, kotrež zdźělenku wobsahuje a opcionalnu hódnotu wróća.
Konstanty MB_xx dialogowy typ, ličbu a typ tłóčatkow, kotrež so maja pokazać a typ symbola podawaja. Přidawajo swoje date hódnoty, tworja bitowe mustry, kotrež napohlad dialoga MsgBox definuja.

Syntaksa:

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

Parametry:

prompt: String expression displayed as a message in the dialog box. Line breaks can be inserted with Chr$(13).

title: String expression displayed in the title bar of the dialog. If omitted, the title bar displays the name of the respective application.

buttons: Any integer expression that specifies the dialog type, as well as the number and type of buttons to display, and the icon type. buttons represents a combination of bit patterns, that is, a combination of elements can be defined by adding their respective values:

Typ wróćenja:

Opcionalna cyła ličba kaž horjeka w kajkosćach IDxx wopisana.

Přikład:


    txt = s.InputBox('Prošu zapodajće sadu:', "Waženy wužiwar")
    s.MsgBox(txt, s.MB_ICONINFORMATION, "Wobkrućenje sady")

Za podrobne informacije čitajće prošu Input/Output to Screen with Python we wikiju.

Now

Wróći aktualny systemowy datum a čas jako natiwny objekt Python datetime.datetime.

Syntaksa:

svc.Now(): datetime

Přikład:


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

RGB

Wróći cyłoličbowu barbowu hódnotu, kotraž z čerwjenych, zelenych a módrych komponentow wobsteji.

Syntaksa:

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

Parametry:

red: Any integer expression that represents the red component (0-255) of the composite color.

green: Any integer expression that represents the green component (0-255) of the composite color.

blue: Any integer expression that represents the blue component (0-255) of the composite color.

The resulting Long value is calculated with the following formula:
Result = red×65536 + green×256 + blue.

Under VBA compatibility mode (Option VBASupport 1), the Long value is calculated as
Result = red + green×256 + blue×65536
See RGB Function [VBA]

The color picker dialog helps computing red, green and blue components of a composite color. Changing the color of text and selecting Custom color displays the color picker dialog.

Typ wróćenja:

Integer

Přikład:


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

Xray

Přepytujće objekty abo wariable Uno.

Syntaksa:

svc.Xray(obj: any)

Parametry:

obj: Wariabla abo objekt UNO.

Přikład:


    bas.Xray(bas.StarDesktop)

Wšě rutiny Basic ScriptForge abo identifikatory, kotrež so z podsmužku „_“ započinaja, su za interne wužiwanje wuměnjene. Njejsu za to myslene, so w makrach Basic abo skriptach Python wužiwać.

GlobalScope specifier

Programowanje ze skriptami Python

uno.fileUrlToSystemPath()

uno.systemPathToFileUrl()

Input/Output to Screen with Python we wikiju

XSCRIPTCONTEXT.getComponentContext()

uno.getComponentContext()

platform.system()

os.pathsep()