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.
Quando avviate le macro Python dal menu , il file di output standard Python non è disponibile. Per maggiori informazioni consultate 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() |
|
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