Servizio ScriptForge.Basic

Il servizio ScriptForge.Basic propone una raccolta di metodi di LibreOffice Basic da eseguire in ambiente Python. I metodi del servizio Basic riproducono esattamente la sintassi e il comportamento delle funzioni incorporate in Basic.

Esempio tipico:


   bas.MsgBox('Visualizza questo testo in un riquadro di dialogo da un script Python')

L'uso del servizio ScriptForge.Basic è limitato agli script in Python.

Invocazione del servizio

Prima di usare il servizio Basic, importate il metodo CreateScriptService() dal modulo scriptforge:


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

Proprietà

Nome	Sola lettura	Tipo	Descrizione
MB_OK, MB_OKCANCEL, MB_RETRYCANCEL, MB_YESNO, MB_YESNOCANCEL	Sì	Integer	Valori: 0, 1, 5, 4, 3
MB_ICONEXCLAMATION, MB_ICONINFORMATION, MB_ICONQUESTION, MB_ICONSTOP	Sì	Integer	Valori: 48, 64, 32, 16
MB_ABORTRETRYIGNORE, MB_DEFBUTTON1, MB_DEFBUTTON2, MB_DEFBUTTON3	Sì	Integer	Valori: 2, 128, 256, 512
IDABORT, IDCANCEL, IDIGNORE, IDNO, IDOK, IDRETRY, IDYES	Sì	Integer	Valori: 3, 2, 5, 7, 1, 4, 6 Costanti che indicano il pulsante selezionato nella finestra MsgBox.
StarDesktop	Sì	Oggetto UNO	Restituisce l'oggetto StarDesktop che rappresenta l'applicazione LibreOffice.
ThisComponent	Sì	Oggetto UNO	Se il componente attuale fa riferimento a un documento di LibreOffice, questo metodo restituisce l'oggetto UNO che rappresenta in documento. Questa proprietà restituisce None quando il componente corrente non corrisponde a un documento.
ThisDatabaseDocument	Sì	Oggetto UNO	Se lo script è stato eseguito da un documento di Base o da uno qualsiasi dei suoi sottocomponenti questo metodo restituisce il componente principale dell'istanza di Base. Altrimenti questa proprietà restituisce None.

Elenco dei metodi del servizio 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

Converte un'espressione numerica o una stringa in un oggetto nativo di Python datetime .datetime.

Questo metodo rende accessibile agli script in Python la funzione incorporata in Basic CDate.

Sintassi:

svc.CDate(expression: any): obj

Parametri:

espressione: un'espressione numerica o una stringa che rappresenta una data.

Quando si converte l'espressione di una stringa, la data e l'ora devono essere inserite in uno dei formati di data accettati definiti nelle impostazioni locali (si veda - LIngue e impostazioni locali - Generale), oppure nel formato di data ISO (attualmente è accettato solo il formato ISO con trattini, per es. "31-12-2012"). Nelle espressioni numeriche, i valori alla sinistra del separatore decimale rappresentano la data, che parte dal 31 dicembre 1899. I valori alla destra del separatore decimale rappresentano l'ora.

Esempio:


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

CDateFromUnoDateTime

Converte la rappresentazione di una data/orario di un oggetto UNO in un oggetto datetime.datetime nativo in Python.

Sintassi:

svc.CDateFromUnoDateTime(unodate: uno): obj

Parametri:

unodate: un oggetto data/ora della libreria UNO di uno dei seguenti tipi: com.sun.star.util.DateTime, com.sun.star.util.Date o com.sun.star.util.Time

Esempio:

L'esempio seguente crea un oggetto com.sun.star.util.DateTime e lo converte in un oggetto datetime.datetime di 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

Converte la rappresentazione di una data in un oggetto com.sun.star.util.DateTime.

Sintassi:

svc.CDateToUnoDateTime(date: obj): uno

Parametri:

data: un oggetto data/orario in Python di uno dei seguenti tipi: datetime.datetime, datetime.date, datetime.time, float (time.time) o time.struct_time.

Esempio:


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

Parametri:

intervallo: un'espressione in formato stringa della seguente tabella, che specifica l'intervallo della data o dell'orario.

interval (valore stringa)	Spiegazione
yyyy	Anno
q	Trimestre
m	Mese
y	Giorno dell'anno
w	Giorno della settimana
ww	Settimana dell'anno
d	Giorno
h	Ora
n	Minuto
s	Secondo

numero: un'espressione numerica che specifica con quale frequenza il valore dell'intervallo verrà aggiunto se positivo, o sottratto se negativo.

date: un valore inserito di tipo datetime.datetime, il valore interval sarà aggiunto per il numero number di volte a questo valore datetime.datetime.

Valore restituito:

Un valore di tipo datetime.datetime.

Esempio:


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

DateDiff

Restituisce il numero di intervalli di data od ora che trascorrono tra i due valori di data/ora indicati.

Sintassi:

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

Parametri:

interval: un'espressione in formato stringa che specifica l'intervallo tra date, come meglio dettagliato nel metodo DateAdd sopra indicato.

date1, date2: i due valori datetime.datetime da confrontare.

firstdayofweek: (PrimoGiornoSettimana) parametro facoltativo che specifica il giorno iniziale della settimana.

valore firstdayofweek	Spiegazione
0	Usa il valore predefinito di sistema
1	Domenica (predefinito)
2	Lunedì
3	Martedì
4	Mercoledì
5	Giovedì
6	Venerdì
7	Sabato

firstweekofyear: un parametro facoltativo che specifica la settimana iniziale dell'anno.

valore firstweekofyear	Spiegazione
0	Usa il valore predefinito di sistema
1	La settimana 1 è quella che comprende il 1° gennaio (predefinito)
2	La settimana 1 è la prima settimana che comprende quattro o più giorni di quell'anno
3	La settimana 1 è la prima settimana che comprende solo giorni del nuovo anno

Valore restituito:

Un numero.

Esempio:


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

DatePart

La funzione DatePart restituisce la parte specificata di una data.

Sintassi:

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

Parametri:

interval: un'espressione in formato stringa che specifica l'intervallo tra date, come meglio dettagliato nel metodo DateAdd sopra indicato.

data - La data/ora dalla quale viene calcolato il risultato.

firstdayofweek, firstweekofyear: parametri opzionali che specificano rispettivamente il giorno di inizio della settimana e la prima settimana dell'anno, come meglio dettagliato in precedenza per il metodo DateDiff.

Valore restituito:

La parte estratta dalla data/ora specificata.

Esempio:


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

DateValue

Calcola il valore di una data da una stringa che rappresenta una data.

Sintassi:

svc.DateValue(date: str): datetime

Parametri:

date: la stringa contenente la data da convertire in un oggetto Date.

La stringa passata a DateValue dev'essere espressa in uno dei formati di data definiti dalle impostazioni locali (vedere - Lingue e impostazioni locali - Generale) o nel formato di data ISO "aaaa-mm-gg" (anno, mese e giorno separati da trattini).

Valore restituito:

La data calcolata.

Esempio:


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

Format

Converte un numero in una stringa e la formatta in base al formato specificato.

Sintassi:

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

Parametri:

espressione: espressione numerica da convertire in una stringa formattata.

format: (formato) stringa che specifica il codice di formato per il numero. Se format viene omesso, la funzione Format opera come la funzione LibreOffice Basic Str().

Valore restituito:

Stringa di testo.

Codici di formato

L'elenco seguente descrive i codici che potete utilizzare per formattare un'espressione numerica:

0: se espressione presenta una cifra nella posizione dello 0 nel codice del formato, viene visualizzata quella cifra, diversamente viene visualizzato uno zero.

Se espressione è formata da un numero inferiore di cifre rispetto al numero di zeri del codice del formato (da qualunque parte del separatore decimale), viene visualizzato il numero appropriato di zeri iniziali o finali. Se a sinistra del separatore decimale l'espressione contiene più cifre rispetto al numero di zeri del codice del formato, le cifre aggiuntive vengono visualizzate senza modifiche.

I decimali dell'espressione vengono arrotondati in base al numero di zeri che compaiono dopo il separatore decimale nel codice del formato.

#: se espressione presenta una cifra nella posizione del segnaposto # nel codice del formato viene visualizzata quella cifra, altrimenti in quella posizione non viene visualizzato nulla.

Questo simbolo è gestito come lo 0, ad eccezione del fatto che gli zeri iniziali e finali non vengono visualizzati se il codice del formato contiene più caratteri # delle cifre dell'espressione. Vengono visualizzate solo le cifre rilevanti dell'espressione.

.: il segnaposto decimale determina il numero di cifre decimali a sinistra e a destra del separatore.

Se il codice del formato contiene solo caratteri segnaposto # a sinistra di questo simbolo, i numeri inferiori a 1 iniziano con un separatore decimale. Per visualizzare sempre uno zero all'inizio dei numeri decimali, usate 0 come segnaposto per la prima cifra a sinistra del separatore decimale.

%: moltiplica l'espressione per 100 e inserisce il segno di percentuale (%) nel punto in cui l'espressione compare nel codice del formato.

E- E+ e- e+ : se il codice del formato contiene almeno un segnaposto per una cifra (0 o #) a destra del simbolo E-, E+, e- o e+, l'espressione viene formattata con la notazione scientifica o esponenziale. La lettera E o e viene inserita tra il numero e l'esponente. Il numero di segnaposti per le cifre a destra del simbolo determina il numero di cifre dell'esponente.

Se l'esponente è negativo, viene visualizzato un segno meno direttamente davanti agli esponenti con E-, E+, e-, e+. Se l'esponente è positivo, viene visualizzato solo un segno più davanti agli esponenti con E+ o e+.

Il codice del formato può comprendere un delimitatore di migliaia racchiuso tra i segnaposto per le cifre (0 o #).

L'uso del punto come separatore per le migliaia o come separatore decimale dipende dalle impostazioni regionali. Il carattere effettivamente visualizzato come separatore decimale dipende dal formato numerico impostato nel vostro sistema. Gli esempi qui illustrati si riferiscono a un sistema con l'impostazione locale "US".

- + $ ( ) space: i caratteri più (+), meno (-), dollaro ($), spazio o parentesi inseriti direttamente nel codice del formato vengono visualizzati in modo letterale.

Per visualizzare caratteri diversi da quelli qui elencati, dovete farli precedere da una barra rovesciata (\) o racchiuderli tra virgolette (" ").

\ : La barra rovesciata visualizza il carattere successivo nel codice del formato.

I caratteri del codice del formato che possiedono un significato speciale possono essere visualizzati in modo letterale solo se sono preceduti da una barra rovesciata. In questi casi, la barra rovesciata non viene visualizzata, a meno che non sia anch'essa preceduta da una barra rovesciata (\\).

I caratteri che devono essere preceduti da una barra rovesciata nel codice del formato per essere visualizzati in modo letterale sono i caratteri di formattazione della data e dell'ora (a, c, d, h, m, n, p, q, s, t, w, y, /, :), i caratteri di formattazione dei numeri (#, 0, %, E, e, virgola, punto) e i caratteri di formattazione delle stringhe (@, &, <, >, !).

In alternativa, potete usare i seguenti formati numerici predefiniti. Ad eccezione di "Numero generale", tutti i codici di formato predefiniti restituiscono un numero decimale con due cifre dopo il separatore.

Per usare i formati predefiniti, dovete indicarne il nome tra virgolette.

Formati predefiniti

General Number: i numeri sono visualizzati nella forma in cui vengono digitati.

Currency: inserisce il simbolo del dollaro davanti al numero e racchiude i numeri negativi tra parentesi.

Fixed: mostra almeno una cifra davanti al separatore decimale.

Standard:mostra i numeri con un separatore di migliaia.

Percent: moltiplica il numero per 100 e aggiunge il segno di percentuale alla fine.

Notazione scientifica: visualizza i numeri in formato scientifico (ad esempio, 1,00E+03 per 1000).

Il codice di formato può essere diviso in tre sezioni separate da punti e virgola. La prima parte definisce il formato per i valori positivi, la seconda il formato per i valori negativi, la terza il formato per lo zero. Se specificate un solo codice di formato, questo viene applicato a tutti i numeri.

È possibile configurare le impostazioni locali utilizzate in LibreOffice Basic per la formattazione di numeri, date e valute in - Lingue e impostazioni locali - Generale. Nei codici di formato Basic, il punto decimale (.) viene sempre usato come segnaposto per il separatore dei decimali definito nelle impostazioni locali e sarà sostituito dal carattere corrispondente.

Lo stesso vale per le impostazioni di data, ora e valuta. Il codice in formato Basic viene interpretato e visualizzato in base alla versione locale prescelta.

Esempio:


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

GetDefaultContext

Restituisce il contesto predefinito della fabbrica di servizio del processo, se esiste, diversamente restituisce un riferimento nullo.

GetDefaultContext è un'alternativa al metodo getComponentContext() disponibile nella variabile globale XSCRIPTCONTEXT o dal modulo uno.py.

Sintassi:

svc.GetDefaultContext(): uno

Valore restituito:

Viene utilizzato il contesto del componente predefinito, quando s'istanziano dei servizi tramite XMultiServiceFactory. Per maggiori informazioni, vedete il capitolo Professional UNO della Guida per gli sviluppatori api.libreoffice.org.

Esempio:


    ctx = bas.GetDefaultContext()

GetGuiType

Restituisce un valore numerico che specifica l'interfaccia grafica. Questa funzione viene fornita solamente per retrocompatibilità con le versioni precedenti.

Fate riferimento al metodo system() del modulo platform di Python per identificare il sistema operativo.

Sintassi:

svc.GetGuiType(): int

Esempio:


    n = bas.GetGuiType()

GetPathSeparator

Restituisce il separatore di directory dipendente dal sistema operativo utilizzato per specificare i percorsi dei file.

Usate os.pathsep dal modulo os di Python per identificare il separatore usato nei percorsi.

Sintassi:

svc.GetPathSeparator(): str

Esempio:


    sep = bas.GetPathSeparator()

GetSystemTicks

Restituisce il numero di tick (ticchettii) forniti dal sistema operativo. Potete usare questa funzione per ottimizzare alcuni processi. Usate questo metodo per stimare il tempo in millisecondi:

Sintassi:

svc.GetSystemTicks(): int

Esempio:


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

GlobalScope.BasicLibraries

Restituisce l'oggetto UNO che contiene tutte le librerie e moduli condivisi con Basic.

Questo metodo è l'equivalente in Python di GlobalScope.BasicLibraries degli script in Basic.

Sintassi:

svc.GlobalScope.BasicLibraries(): uno

Valore restituito:

com.sun.star.script.XLibraryContainer

Esempio:

Il seguente esempio carica la libreria Gimmicks di Basic, se questa non è già caricata.


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

GlobalScope.DialogLibraries

Restituisce l'oggetto UNO che contiene tutte le librerie condivise con finestre di dialogo.

Questo metodo è l'equivalente in Python di GlobalScope.DialogLibraries degli script in Basic.

Sintassi:

svc.GlobalScope.DialogLibraries(): uno

Valore restituito:

com.sun.star.comp.sfx2.DialogLibraryContainer

Esempio:

Il seguente esempio mostra una finestra di dialogo con i nomi di tutte le librerie contenenti finestre di dialogo.


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

InputBox

Sintassi:

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

Parametri:

prompt: stringa visualizzata come messaggio nella finestra di dialogo.

title (titolo): stringa visualizzata nella barra del titolo della finestra di dialogo.

default (predefinito): stringa visualizzata nella casella di testo come valore predefinito se non viene specificato nessun valore.

xpostwips: numero intero che specifica la posizione orizzontale della finestra di dialogo. La posizione è una coordinata assoluta e non fa riferimento alla finestra di LibreOffice.

ypostwips: numero intero che specifica la posizione verticale della finestra di dialogo. La posizione è una coordinata assoluta e non fa riferimento alla finestra di LibreOffice.

Se xpostwips e ypostwips vengono omessi, la finestra di dialogo viene centrata sullo schermo. La posizione è specificata in twip.

Valore restituito:

String

Esempio:


    txt = s.InputBox('Inserisci una frase:', "Caro/a utente")
    s.MsgBox(txt, s.MB_ICONINFORMATION, "Conferma della frase")

Per informazioni più approfondite fate riferimento alla pagina wiki Input e Output sullo schermo usando Python (in inglese).

MsgBox

Visualizza un riquadro di dialogo contenente un messaggio e restituisce un valore opzionale.
Le costanti MB_xx specificano il tipo di finestra di dialogo, il numero e il tipo di pulsanti da visualizzare e anche il tipo di icona. Aggiungendo i loro rispettivi valori si crea la sequenza di bit, che definisce l'aspetto del riquadro di dialogo MsgBox.

Sintassi:

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

Parametri:

prompt: stringa visualizzata come messaggio nella finestra di dialogo. Le interruzioni di riga possono essere inserite con Chr$(13).

title (titolo): stringa visualizzata nella barra del titolo della finestra di dialogo. Se questa stringa è omessa, la barra del titolo visualizza il nome dell'applicazione corrispondente.

buttons (pulsanti): numero intero che specifica il tipo di finestra di dialogo, nonché il numero e il tipo dei pulsanti da visualizzare e il tipo di icona. buttons rappresenta una combinazione di modelli di bit, cioè una combinazione di elementi che può essere definita sommando i rispettivi valori:

Valore restituito:

Un numero intero opzionale, come dettagliato in precedenza nelle proprietà IDxx.

Esempio:


    txt = s.InputBox('Inserisci una frase:', "Caro/a utente")
    s.MsgBox(txt, s.MB_ICONINFORMATION, "Conferma della frase")

Per informazioni più approfondite fate riferimento alla pagina wiki Input e Output sullo schermo usando Python (in inglese).

Now

Restituisce la data e ora corrente del sistema come oggetto datetime.datetime nativo di Python.

Sintassi:

svc.Now(): datetime

Esempio:


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

RGB

Restituisce un valore intero per il colore formato dai componenti rosso, verde e blu.

Sintassi:

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

Parametri:

red (rosso): numero intero che rappresenta il componente rosso (0-255) del colore composito.

green (verde): numero intero che rappresenta il componente verde (0-255) del colore composito.

blue (blu): numero intero che rappresenta il componente blu (0-255) del colore composito.

Il valore risultante di tipo Long è calcolato con la seguente formula:
Result = red×65536 + green×256 + blue.

In modalità compatibilità VBA (Option VBASupport 1), il valore di tipo Long è calcolato come
Result = red + green×256 + blue×65536
Vedere la Funzione RGB [VBA]

La finestra di dialogo per la scelta del colore aiuta a calcolare i componenti rosso, verde e blu di un colore composito. La modifica del colore del testo e la selezione di un colore personalizzato richiama la finestra di dialogo per la scelta del colore.

Valore restituito:

Integer

Esempio:


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

Xray

Ispeziona oggetti e variabili UNO.

Sintassi:

svc.Xray(obj: any)

Parametri:

obj: una variabile o un oggetto UNO.

Esempio:


    bas.Xray(bas.StarDesktop)

Tutte le routine e gli identificatori Basic di ScriptForge che iniziano con un carattere di sottolineatura "_" sono riservati per uso interno. Non è previsto il loro utilizzo nelle macro in Basic o negli script in Python.

Modificatore GlobalScope

Programmare con script Python

uno.fileUrlToSystemPath()

uno.systemPathToFileUrl()

Input e output sullo schermo usando Python sul wiki (in inglese)

XSCRIPTCONTEXT.getComponentContext()

uno.getComponentContext()

platform.system()

os.pathsep()