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, fate 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.

tip

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


Importazione di moduli

warning

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 condivisi di installazione LibreLogo e TableSample utilizzano il modulo uno.py.

Altri esempi Python-Basic

Python UNO

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, visitate il sito di LibreOffice Application Programming Interface (API) o scaricate LibreOffice Software Development Kit (SDK).

L'impostazione di un modulo Python incorporato in un documento viene illustrata di seguito, ad eccezione della gestione, non trattata in dettaglio:


            import uno, sys
            
            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
        

Sosteneteci!