Contenu
Index 🔎︎

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

Ce service est disponible à partir de LibreOffice 7.2 et supérieures.

Typical example:

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

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.

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

### Syntaxe :

svc.CDate(expression: any): obj

### Paramètres :

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

Lorsque vous convertissez une expression de chaîne, la date et l'heure doivent être saisies dans l'un des modèles d'acceptation de date définis pour votre configuration de paramètres régionaux (voir LibreOffice - Preferences Outils - Options - Paramètres linguistiques - Langues ou au format de date ISO (momentanément, seul le format ISO avec tirets, par exemple "2012-12-31" est accepté). Dans les expressions numériques, les valeurs à gauche de la décimale représentent la date, à partir du 31 décembre 1899. Les valeurs à droite de la décimale représentent l'heure.

### Exemple :

        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.

### Syntaxe :

svc.CDateFromUnoDateTime(unodate: uno): obj

### Paramètres :

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

### Exemple :

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.

### Syntaxe :

svc.CDateToUnoDateTime(date: obj): uno

### Paramètres :

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.

### Exemple :

        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.

### Syntaxe :

svc.ConvertFromUrl(url: str): str

### Paramètres :

url: An absolute file: URL.

### Valeur de retour :

A system path file name.

### Exemple :

        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.

### Syntaxe :

svc.ConvertToUrl(systempath: str): str

### Paramètres :

systempath: A system file name as a string.

### Valeur de retour :

A file: URL as a string.

### Exemple :

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

## CreateUnoService

Instantiates a UNO service with the ProcessServiceManager.

### Syntaxe :

svc.CreateUnoService(servicename: str): uno

### Paramètres :

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

### Exemple :

        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.

### Syntaxe :

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

### Paramètres :

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

interval (string value) | Explication
yyyy | Année
q | Trimestre
m | Mois
y | Jour de l'année
w | Jour de la semaine
ww | Semaine de l'année
d | Jour
h | Heure
n | Minute
s | Seconde

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.

### Valeur de retour :

A datetime.datetime value.

### Exemple :

        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.

### Syntaxe :

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

### Paramètres :

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

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

firstdayofweekt : un paramètre facultatif spécifiant le premier jour de la semaine.

valeur firstdayofweek | Explication
0 | Utiliser la valeur système par défaut
1 | Dimanche (par défaut)
2 | Lundi
3 | Mardi
4 | Mercredi
5 | Jeudi
6 | Vendredi
7 | Samedi

firstweekofyear : un paramètre facultatif spécifiant la première semaine de l'année.

valeur firstweekofyear | Explication
0 | Utiliser la valeur système par défaut
1 | La semaine 1 est la semaine du 1er janvier (par défaut)
2 | La semaine 1 est la première semaine contenant quatre jours ou plus de cette même année
3 | La semaine 1 est la première semaine contenant uniquement des jours de la nouvelle année

### Valeur de retour :

A number.

### Exemple :

        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.

### Syntaxe :

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

### Paramètres :

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.

### Valeur de retour :

The extracted part for the given date/time.

### Exemple :

        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.

### Syntaxe :

svc.DateValue(date: str): datetime

### Paramètres :

Date: expression de chaîne qui contient la date à calculer. Contrairement à la fonction DateSerial qui transmet les années, les mois et les jours en tant que valeurs numériques distinctes, la fonction DateValue demande que la chaîne de date soit conforme à l'un des motifs d'acceptation de date définis dans le paramètre régional. (voirLibreOffice - Préférences Outils - Options - Paramètres linguistiques - Langues) ou au format de date ISO (momentanément, seul le format ISO avec des tirets, e.g. "2012-12-31" est accepté).

### Valeur de retour :

The computed date.

### Exemple :

        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.

### Syntaxe :

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

### Paramètres :

expression: expression numérique à convertir en chaîne de caractères formatée.

format : chaîne de caractères spécifiant le code de format du nombre. Siformat est omis, la fonction Format fonctionne comme la fonction LibreOffice Basic Str().

### Valeur de retour :

Chaîne de texte.

### Formatting Codes

La liste suivante décrit les codes à utiliser pour formater une expression numérique :

0: Si expression possède un chiffre à la position du 0 dans le code de format, ce chiffre s'affiche, ans le cas contraire, un zéro est affiché.

Si expression possède moins de chiffres que le nombre de zéros du code de format (de chaque côté de la décimale), les zéros à gauche et à droite apparaissent. Si expression possède plus de chiffres à gauche du séparateur de décimales que le nombre de zéros dans le code de format, les chiffres supplémentaires sont affichés sans formatage.

Les décimales dans l'expression sont arrondies en fonction du nombre de zéros apparaissant après le séparateur de décimales dans le code de format.

#: Si expression possède un chiffre à la position du substituant # dans le code de format, ce chiffre s'affiche. Dans le cas contraire, rien ne s'affiche à cette position.

Ce symbole a la même fonction que le 0, à l'exception du fait que les zéros à gauche ou à droite ne sont pas affichés s'il y a plus de caractères # dans le code de format que de chiffres dans l'expression. Seuls les chiffres pertinents de l'expression sont affichés.

.: Le substituant décimal détermine le nombre de décimales à gauche et à droite du séparateur de décimales.

Si le code de format ne contient que des substituants # à gauche de ce symbole, les nombres inférieurs à 1 débutent par un séparateur de décimales. Pour toujours afficher un zéro à gauche des nombres fractionnels, utilisez 0 comme substituant pour le premier chiffre à gauche du séparateur de décimales.

%: multiplie l'expression par 100 et insert le signe pourcentage (%) où l'expression apparaît dans le code de format.

E- E+ e- e+ : si le code de format comporte au moins un substituant de chiffre (0 ou #) situé à droite du symbole E-, E+, e- ou e+, l'expression est formatée au format scientifique ou exponentiel. La lettre E ou e est insérée entre le nombre et l'exposant. Le nombre de substituants des chiffres situés à droite du symbole détermine le nombre de chiffres contenus dans l'exposant.

Si l'exposant a une valeur négative, un signe moins s'affiche entre le symbole E-, E+, e-, e+ et la valeur de l'exposant. Si l'exposant a une valeur positive, le signe plus ne s'affiche qu'entre le symbole E+ ou e+ et la valeur de l'exposant.

Le séparateur de milliers est affiché si le code de format comporte un séparateur compris entre des substituants de chiffres (0 ou #).

L'utilisation du point comme séparateur de décimales et de milliers dépend des paramètres régionaux. Lorsque vous saisissez un nombre directement en code source Basic, utilisez toujours un point comme séparateur de décimales. Le caractère utilisé comme séparateur de décimales dépend du format numérique des paramètres de votre système.

- + $ ( ) space : Les signes plus (+), moins (-), dollar ($), espace, ou des parenthèses saisis directement dans le code de format sont affichés sous forme de caractères littéraux.

Pour afficher des caractères autres que ceux listés ici, vous devez les faire précéder d'une barre oblique inverse (\) ou les saisir entre guillemets (" ").

\ : La barre oblique inverse affiche le caractère suivant dans le code de format.

Les caractères du code de format ayant une signification spéciale ne peuvent être affichés en tant que caractères littéraux que s'ils sont précédés d'une barre oblique inverse. La barre oblique inverse ne s'affiche pas, sauf si vous saisissez une double barre oblique inverse (\\) dans le code de format.

Les caractères devant être précédés par une barre oblique inverse dans la description de format pour s'afficher en tant que caractères littéraux sont les caractères de formatage de date et d'heure (a, c, d, h, m, n, p, q, s, t, w, y, /, :), les caractères de formatage numérique (#, 0, %, E, e, virgule, point) et les caractères de formatage de chaînes de caractères (@, &, <, >, !).

Vous pouvez aussi utiliser les formats numériques prédéfinis suivants. À l'exception de General Number, tous les codes de format prédéfinies renvoient les nombres en tant que nombres décimaux à deux décimales.

Si vous utilisez des formats prédéfinis, le nom du format doit être saisi entre guillemets.

### Predefined Formats

General Number : les nombres sont affichés tels qu'ils ont été saisis.

Currency : insère le caractère dollar avant le nombre et place les nombres négatifs entre parenthèses.

Fixed : affiche au moins un chiffre avant le séparateur de décimales.

Standard : affiche les nombres avec un séparateur de milliers.

Percent : multiplie le nombre par 100 et ajoute le signe pourcentage au nombre.

Scientific : affiche les nombres au format scientifique (par exemple, 1.00E+03 pour 1000).

Un code de format peut être divisée en trois sections séparées par des points-virgules. La première partie définit le format des valeurs positives, la seconde le format des valeurs négatives et la troisième le format des valeurs nulles. Si vous ne spécifiez qu'un code de format, celui-ci s'applique à tous les nombres.

Vous pouvez définir le paramètre local utilisé pour contrôler le formatage des nombres, des dates et monétaire dans LibreOffice Basic dans LibreOffice - Préférences Outils - Options - Paramètres linguistiques - Langues. Dans les codes de format Basic, le point décimal (.) est toujours utilisé comme substituant pour le séparateur décimal défini dans votre paramètre local et sera remplacé par le caractère correspondant.

Cela s'applique également aux paramètres de l'environnement linguistique relatifs aux formats de date, d'heure et de monnaie. La description de format Basic est interprétée et affichée en fonction des paramètres de l'environnement linguistique.

### Exemple :

        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.

### Syntaxe :

svc.GetDefaultContext(): uno

### Valeur de retour :

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.

### Exemple :

        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.

### Syntaxe :

svc.GetGuiType(): int

### Exemple :

        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.

### Syntaxe :

svc.GetPathSeparator(): str

        svc.GetPathSeparator(): str

### Exemple :

        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:

### Syntaxe :

svc.GetSystemTicks(): int

### Exemple :

        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.

### Syntaxe :

svc.GlobalScope.BasicLibraries(): uno

### Valeur de retour :

com.sun.star.script.XLibraryContainer

### Exemple :

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.

### Syntaxe :

svc.GlobalScope.DialogLibraries(): uno

### Valeur de retour :

com.sun.star.comp.sfx2.DialogLibraryContainer

### Exemple :

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

### Syntaxe :

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

### Paramètres :

prompt : expression au format chaîne de caractères affichée comme message dans la boîte de dialogue.

title: expression de chaîne affichée dans la barre de titre de la boîte de dialogue.

default : expression de chaîne affichée dans la zone de texte en tant qu'expression par défaut en l'absence d'autre entrée.

xpostwips : expression au format nombre entier spécifiant la position horizontale de la boîte de dialogue. La position est une coordonnée absolue et ne se rapporte pas à la fenêtre de l'application de LibreOffice.

ypostwips : expression au format nombre entier spécifiant la position horizontale de la boîte de dialogue. La position est une coordonnée absolue et ne se rapporte pas à la fenêtre de LibreOffice.

Sixpostwips etypostwips sont omis, la boîte de dialogue est centrée sur l'écran. La position est spécifiée dans twips.

### Valeur de retour :

string

### Exemple :

        txt = s.InputBox('Please enter a phrase:', "Dear user")
        s.MsgBox(txt, 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.

### Syntaxe :

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

### Paramètres :

prompt: expression de chaîne affichée comme un message dans la boîte de dialogue. Les sauts de lignes peuvent être insérés avec Chr$(13).

title: expression de chaîne affichée dans la barre de titre d'une boîte de dialogue. Si omise, la barre de titre affiche le nom de l'application correspondante.

buttons : expression au format nombre entier spécifiant le type de la boîte de dialogue, le nombre et le type de boutons à afficher, ainsi que le type d'icône. buttons représente une combinaison de motifs binaires, c'est-à-dire une combinaison d'éléments déterminée par l'ajout de leurs valeurs respectives :

### Valeur de retour :

An optional integer as detailed in above IDxx properties.

### Exemple :

        txt = s.InputBox('Please enter a phrase:', "Dear user")
        s.MsgBox(txt, 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.

### Syntaxe :

svc.Now(): datetime

### Exemple :

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

## RGB

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

### Syntaxe :

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

### Paramètres :

red : toute expression au format nombre entier représentant le composant rouge (0-255) de la couleur composite.

green : toute expression au format nombre entier représentant le composant vert (0-255) de la couleur composite.

blue : toute expression au format nombre entier représentant le composant bleu (0-255) de la couleur composite.

Le dialogue color pickeraide à calculer les composantes rouge, vert et bleu d'une couleur composite. Changer la couleur du texte and selecting Custom color affiche le dialogue color picker.

### Valeur de retour :

integer

### Exemple :

        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.

### Syntaxe :

svc.ThisComponent(): uno

### Exemple :

        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.

### Syntaxe :

svc.ThisDatabaseDocument(): uno

### Exemple :

        db_doc = svc.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.

### Syntaxe :

svc.Xray(obj: any)

### Paramètres :

obj: A variable or Uno object.

### Exemple :

        svc.Xray(svc.StarDesktop)

Toutes les routines ou identificateurs Basic ScriptForge précédés d'un trait de soulignement "_" sont réservés à un usage interne. Ils ne sont pas destinés à être utilisés dans les macros Basic.

Rubriques connexes

Spécificateur GlobalScope

Programmer avec des Scripts Python

uno.fileUrlToSystemPath()

uno.systemPathToFileUrl()

Input/Output to Screen with Python on the wiki

XSCRIPTCONTEXT.getComponentContext()

uno.getComponentContext()

platform.system()

os.pathsep()