Contenuto

# Programmare con script Python

Una macro Python è una funzione all'interno di un file .py, identificata come un modulo. A differenza di LibreOffice Basic e la sua dozzina di servizi o funzioni di oggetti UNO, le macro Python utilizzano l'oggetto singolo UNO XSCRIPTCONTEXT, condiviso con JavaScript e BeanShell. La tuple globale g_exportedScripts elenca in modo esplicito le macro selezionabili da un modulo. I moduli Python possiedono una logica di codice autonoma e sono indipendenti l'uno dall'altro.

## Variabile globale XSCRIPTCONTEXT

Le funzioni Basic UNO originali si possono dedurre dalla variabile globale XSCRIPTCONTEXT. Per una descrizione di XSCRIPTCONTEXT esaustiva, fare riferimento all'API di LibreOffice. I metodi di XSCRIPTCONTEXT si riepilogano in:

Metodi | Descrizione | Mappata in Basic come
--- | --- | ---
getDocument() | Il riferimento del documento su cui lo script può operare. | ThisComponent
getDesktop() | Il riferimento del desktop su cui lo script può operare. | StarDesktop
getComponentContext() | Il contesto del componente che lo script può utilizzare per creare altri componenti uno. | GetDefaultContext

Gli script condivisi di installazione HelloWorld e Capitalise illustrano le macro collegate a UNO che fanno uso della variabile globale XSCRIPTCONTEXT.

Quando si avviano le macro Python dal menu Strumenti - Macro - Esegui macro, il file di output standard Python non è disponibile. Per maggiori informazioni consultare il capitolo Input/output sullo schermo.

## Importazione di moduli

XSCRIPTCONTEXT non viene fornito ai moduli importati.

Le librerie di LibreOffice Basic contengono classi, routine e variabili, i moduli Python contengono classi, funzioni e variabili. Le parti comuni delle funzioni Python o UNO riutilizzabili devono essere memorizzate in Macro personaliall'interno del percorso (Profilo utente)/Scripts/python/pythonpath. Le librerie Python aiutano a organizzare i moduli in modo da evitare conflitti di nome. Importate uno.py dentro i moduli condivisi.

Le funzioni BASIC UNO originali si possono dedurre utilizzando il modulo uno.py. Utilizzate la shell interattiva di Python per ottenere una descrizione completa dei moduli mediante i comandi Python dir() e help().

Funzioni | Descrizione | Mappata in Basic come
--- | --- | ---
absolutize() | Restituisce l'URL assoluto di un file dagli URL specificati. |
createUnoStruct() | Crea uno struct UNO o un'eccezione specificata da typeName. | CreateUNOStruct()
fileUrlToSystemPath() | Restituisce un percorso di sistema. | ConvertFromURL()
getClass() | Restituisce la classe di un'eccezione, struct o interfaccia UNO concreta. |
getComponentContext() | Restituisce il contesto del componente UNO utilizzato per inizializzare il tempo di esecuzione (runtime) Python. | GetDefaultContext()
Enum() getConstantByName() | Cerca il valore di una costante IDL fornendo il suo nome esplicito. | Vedere i gruppi di costanti API
isInterface() | Restituisce True (Vero), quando l'oggetto è una classe di un'interfaccia UNO. |
systemPathToFileUrl() | Restituisce un file URL per il percorso di sistema specificato. | ConvertToURL()

Gli script preinstallati LibreLogo, NamedRanges, SetCellColor e TableSample utilizzano il modulo uno.py.

## Altri esempi Python-Basic

UNO e Python | Funzionalità Basic UNO
--- | ---
ctx = uno.getComponentContext() smgr = ctx.getServiceManager() obj = smgr.createInstanceWithContext( .. , ctx) | CreateUnoService()
Vedere Visualizzare una finestra di dialogo | CreateUnoDialog()
Vedere Creazione di un listener | CreateUnoListener()
Vedere Tipi di dati UNO | CreateUnoValue() CreateObject()
| EqualUnoObjects()
ctx = uno.getComponentContext() smgr = ctx.getServiceManager() | GetProcessServiceManager()
def hasUnoInterfaces(obj, *interfaces): return set(interfaces).issubset(t.typeName for t in obj.Types) | HasUnoInterfaces()
| IsUnoStruct()
ctx = uno.getComponentContext() smgr = ctx.getServiceManager() DESK = 'com.sun.star.frame.Desktop' desktop = smgr.createInstanceWithContext(DESK , ctx) | StarDesktop
desktop = smgr.createInstanceWithContext(DESK , ctx) doc = desktop.CurrentComponent | ThisComponent

## Importazione di un modulo incorporato

In modo simile a LibreOffice Basic, che supporta la navigazione e il caricamento dinamico delle librerie, le librerie Python si possono esplorare e importare su richiesta. Per ulteriori informazioni sui contenitori delle librerie, visitare il sito di LibreOffice Application Programming Interface (API) o scaricare LibreOffice Software Development Kit (SDK).

L'importazione di un modulo Python incorporato in un documento è illustrata qui di seguito, la gestione delle eccezioni non è dettagliata:

                import uno, sys, zipimport

                def load_library(library_name: str, module_name=None):
                    """ carica libreria e importa modulo

                    adattato da 'Bibliothèque de fonctions' di Hubert Lambert
                    all'indirizzo https://forum.openoffice.org/fr/forum/viewtopic.php?p=286213"""
                    doc = XSCRIPTCONTEXT.getDocument()  # documento attuale
                    url = uno.fileUrlToSystemPath( \
                        '{}/{}'.format(doc.URL, 'Scripts/python'+library_name))  # ConvertToURL()
                    if not url in sys.path:  # aggiunge percorso se necessario
                        sys.path.insert(0, url)  # doclib ha la precedenza
                    if module_name:  # importa se richiesto
                        return zipimport.zipimporter(url).load_module(module_name)

                def import_embedded_python():
                    ui = load_library("my_gui",'screen_io')  # aggiunge percorso <lib> + importa <module>
                    ui.MsgBox(sys.modules.keys())

                g_exportedScripts = (import_embedded_python,)  # Public macros

Argomenti correlati

Oggetti, funzioni e servizi UNO Basic

Importazione dei moduli Python

Input/output su schermo

Guida agli script Python di LibreOffice