Programação com scripts Python

Uma macro Python é uma função dentro de um ficheiro .py, identificada como um módulo. Ao contrário do LibreOffice Basic e da sua dúzia de funções ou serviços de objetos UNO, as macros Python usam o objeto UNO único XSCRIPTCONTEXT, partilhado com JavaScript e BeanShell. A tupla global g_exportedScripts lista explicitamente as macros selecionáveis de um módulo. Os módulos Python possuem lógica autónoma de código, e são independentes uns dos outros.

Variável global XSCRIPTCONTEXT

As instalações UNO básicas genuínas podem ser inferidas da variável global XSCRIPTCONTEXT. Consulte a API do LibreOffice para obter uma descrição completa do XSCRIPTCONTEXT. Os métodos XSCRIPTCONTEXT resumem-se ao seguinte:

Métodos	Descrição	Mapeado no Basic como
getDocument()	A referência ao documento no qual o script pode operar.	ThisComponent
getDesktop()	A referência ao ambiente de trabalho no qual o script pode operar.	StarDesktop
getComponentContext()	O contexto do componente que o script pode usar para criar outros componentes UNO.	GetDefaultContext

Os scripts partilhados de instalação HelloWorld e Capitalise ilustram as macros relacionadas a UNO que usam a variável global XSCRIPTCONTEXT.

O ficheiro de saída padrão do Python não está disponível ao executar macros do Python no menu Ferramentas - Macros - Executar macro. Consulte Entrada/Saída para o ecrã para mais informações.

Importação de módulos

XSCRIPTCONTEXT não é fornecido para módulos importados.

As bibliotecas BASIC do LibreOffice contêm classes, rotinas e variáveis. Os módulos Python contêm classes, funções e variáveis. Os pedaços comuns de recursos reutilizáveis Python e UNO devem ser armazenados no contentor Minhas Macros em (perfil do utilizador)/Scripts/python/pythonpath. As bibliotecas Python ajudam a organizar os módulos para evitar conflitos de nomes. Importe uno.py nos módulos partilhados.

Os recursos genuínos do UNO BASIC podem ser inferidos utilizando o módulo uno.py. Utilize a consola interativa Python para ter uma descrição completa do módulo utilizando os comandos Python dir() e help().

Funções	Descrição	Mapeado no Basic como
absolutize()	Devolve um URL de ficheiro absoluto a partir dos URLs fornecidos.
createUnoStruct()	Cria uma estrutura ou exceção UNO dada por typeName.	CreateUNOStruct()
fileUrlToSystemPath()	Devolve um caminho do sistema.	ConvertFromURL()
getClass()	Devolve a classe de uma exceção concreta, struct ou interface UNO.
getComponentContext()	Devolve o contexto do componente UNO usado para inicializar o tempo de execução do Python.	GetDefaultContext()
Enum() getConstantByName()	Procura o valor de uma constante de IDL pelo seu nome explícito.	Consultar grupos de constantes da API
isInterface()	Devolve Verdadeiro, quando obj é uma classe de uma interface UNO.
systemPathToFileUrl()	Devolve um URL de arquivo para o caminho do sistema especificado.	ConvertToURL()

Os scripts partilhados de instalação LibreLogo e TableSample usam o módulo uno.py.

Mais exemplos de Python-Basic

Python UNO	Funcionalidades UNO Basic
ctx = uno.getComponentContext() smgr = ctx.getServiceManager() obj = smgr.createInstanceWithContext( .. , ctx)	CreateUnoService()
Veja Abrir uma caixa de diálogo	CreateUnoDialog()
Veja Criar um ouvinte	CreateUnoListener()
Consultar tipos de dados 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

Importar um módulo incorporado

Da mesma forma que o LibreOffice Basic suporta a navegação e o carregamento dinâmico de bibliotecas, as bibliotecas do Python podem ser exploradas e importadas sob pedido. Para mais informações sobre contentores de bibliotecas, visite a API (Interface de Programação de Aplicações) do LibreOffice, ou transfira o Software Development Kit (SDK) do LibreOffice.

A importação de um módulo incorporado do documento Python é ilustrada abaixo, a manipulação de exceção não é detalhada:


            import uno, sys
            
            def load_library(library_name: str, module_name=None):
                """ carregar biblioteca e importar módulo
                
                Adaptado de 'Bibliothèque de fonctions' de Hubert Lambert
                em https://forum.openoffice.org/fr/forum/viewtopic.php?p=286213""" 
                doc = XSCRIPTCONTEXT.getDocument()  # document atual
                url = uno.fileUrlToSystemPath( \
                    '{}/{}'.format(doc.URL, 'Scripts/python'+library_name))  # ConvertToURL()
                if not url in sys.path:  # adicionar o caminho se necessário
                    sys.path.insert(0, url)  # doclib tem precedência
                if module_name:  # importar se for pedido
                    return zipimport.zipimporter(url).load_module(module_name)
            
            def import_embedded_python():
                ui = load_library("my_gui",'screen_io')  # adicionar caminho de <lib> + importar <module> 
                ui.MsgBox(sys.modules.keys())
            
            g_exportedScripts = (import_embedded_python,)  # Public macros

Objetos, funções e serviços BASIC UNO

Importar módulos Python

Entrada/Saída no ecrã

Ajuda para os scripts Python no LibreOffice