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.

note

Questo servizio è disponibile in LibreOffice dalla versione 7.2 in poi.


Esempio tipico:


   svc.MsgBox('Questo messaggio sarà visualizzato in un riquadro di dialogo')
  
warning

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


Invocare il servizio

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


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

Proprietà

Nome

Sola lettura

Tipo

Descrizione

MB_OK, MB_OKCANCEL, MB_RETRYCANCEL, MB_YESNO, MB_YESNOCANCEL

Sì

intero

Valori: 0, 1, 5, 4, 3

MB_ICONEXCLAMATION, MB_ICONINFORMATION, MB_ICONQUESTION, MB_ICONSTOP

Sì

intero

Valori: 48, 64, 32, 16

MB_ABORTRETRYIGNORE, MB_DEFBUTTON1, MB_DEFBUTTON2, MB_DEFBUTTON3

Sì

intero

Valori: 2, 128, 256, 512

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

Sì

intero

Valori: 3, 2, 5, 7, 1, 4, 6
Costanti che indicano il pulsante selezionato nella finestra MsgBox.

StarDesktop

Sì

Oggetto
UNO

L'oggetto StarDesktop rappresenta il Centro di avvio di LibreOffice.


Elenco dei metodi del servizio Basic

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

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

note

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 convertite un'espressione di stringa, la data e l'ora devono essere digitate in uno dei modelli di data accettati definiti nelle vostre impostazioni locali (si veda - Impostazioni della lingua - Lingue), 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 = svc.CDate(1000.25)
    svc.MsgBox(str(d)) # 1902-09-26 06:00:00
    svc.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.


    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

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 = svc.CDateToUnoDateTime(current_datetime)
    svc.MsgBox(str(uno_date.Year) + "-" + str(uno_date.Month) + "-" + str(uno_date.Day))
  

ConvertFromUrl

Restituisce il percorso di sistema di un determinato file file: URL.

Sintassi:

svc.ConvertFromUrl(url: str): str

Parametri:

url: l'URL assoluto del file.

Valore restituito:

Il nome di un percorso di sistema per il file.

Esempio:


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

ConvertToUrl

Restituisce un URL file: per il percorso di sistema specificato.

Sintassi:

svc.ConvertToUrl(systempath: str): str

Parametri:

systempath: un nome di sistema per il file in formato stringa.

Valore restituito:

L'URL del file: in formato stringa.

Esempio:


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

CreateUnoService

Crea un'istanza di un servizio UNO con il ProcessServiceManager.

Sintassi:

svc.CreateUnoService(servicename: str): uno

Parametri:

servicename: il nome completo e qualificato di un servizio come "com.sun.star.ui.dialogs.FilePicker" o 'com.sun.star.sheet.FunctionAccess'.

Esempio:


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

DateAdd

Aggiunge un intervallo a una data od ora per un determinato numero di volte e restituisce la data risultante.

Sintassi:

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

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.

data: Il valore di un determinato oggetto datetime.datetime. Il valore dell'intervallo sarà aggiunto ripetutamente a quello di questa data/ora.

Valore restituito:

Il valore di un oggetto datetime.datetime.

Esempio:


    dt = datetime.datetime(2004, 1, 31)
    dt = svc.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:

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

date1, date2: i valori dei due oggetti 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 = svc.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:

intervallo: 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(svc.DatePart("ww", datetime.datetime(2005,12,31)
    print(svc.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:

Data: espressione di stringa che contiene la data da calcolare. A differenza della funzione DateSerial che passa anni, mesi e giorni come valori numerici separati, la funzione DateValue che da stringa della data sia conforme i modelli accettati per la data definiti nelle vostre impostazioni locali (si veda - Impostazioni della lingua - Lingue) o al formato di data ISO (al momento è accettato solo il formato ISO con trattino breve, ossia "31-12-2012").

Valore restituito:

La data calcolata.

Esempio:


    dt = svc.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 posti 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.

Potete configurare le impostazioni di località utilizzate in LibreOffice Basic per gestire la formattazione di numeri, date e valute in - Impostazioni della lingua - Lingue. Nei codici di formato Basic, il punto decimale (.) viene sempre usato come segnaposto per il separatore dei decimali definito nella vostra area geografica e verrà 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 = svc.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 = svc.GetDefaultContext()
  

GetGuiType

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

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

Sintassi:

svc.GetGuiType(): int

Esempio:


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


    svc.GetPathSeparator(): str
  

Esempio:


    sep = svc.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 = svc.GetSystemTicks()
    time.sleep(1)
    ticks_end = svc.GetSystemTicks()
    svc.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 = svc.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 = svc.GlobalScope.DialogLibraries()
    lib_names = dlg_libs.getElementNames()
    svc.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:

stringa

Esempio:


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

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:

svc.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, MB_ICONINFORMATION, "Conferma della frase")
  
note

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:


    svc.MsgBox(svc.Now(), svc.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.

tip

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:

intero

Esempio:


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

ThisComponent

Se il componente attivo fa riferimento a un documento di LibreOffice, questo metodo restituisce l'oggetto UNO che rappresenta il documento.

Il metodo restituirà None quando il componente attivo non corrisponde a un documento.

Sintassi:

svc.ThisComponent(): uno

Esempio:


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

ThisDatabaseDocument

Se lo script viene eseguito da un documento di Base, o da uno qualsiasi dei suoi sottocomponenti, questo metodo restituisce il componente principale dell'istanza di Base.

Altrimenti questo metodo restituisce None.

Sintassi:

svc.ThisDatabaseDocument(): uno

Esempio:


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

Per approfondire la conoscenza della struttura del componente principale di Base, visitate la pagina relativa alle API OfficeDatabaseDocument (in inglese).


Xray

Ispeziona oggetti e variabili UNO.

Sintassi:

svc.Xray(obj: any)

Parametri:

obj: una variabile o un oggetto UNO.

Esempio:


    svc.Xray(svc.StarDesktop)
  
warning

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.


Sosteneteci!