Conteúdo

# 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 Python a partir do menu Ferramentas - Macros - Executar Macro. Consulte Entrada/Saída para o Ecrã para obter mais informações.

## Importação de módulos

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

LibreOffice As bibliotecas básicas contêm classes, rotinas e variáveis; os módulos Python contêm classes, funções e variáveis. Elementos comuns reutilizáveis do Python ou do UNO devem ser armazenados em As minhas macros dentro de (Perfil do Utilizador)/Scripts/python/pythonpath. As bibliotecas Python ajudam a organizar os módulos para evitar colisões de nomes de módulos. Importe uno.py dentro de módulos partilhados.

É possível explorar as funcionalidades genuínas do BASIC UNO através do módulo uno.py. Utilize o shell interativo do Python para obter uma descrição completa do módulo através dos 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 pré-instalados LibreLogo, NamedRanges, SetCellColor e TableSample utilizam 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()
Utilize os operadores de comparação "==" ou "!=" | 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

À semelhança do LibreOffice Basic, que suporta a navegação e o carregamento dinâmico de bibliotecas, as bibliotecas Python podem ser exploradas e importadas conforme necessário. Para mais informações sobre contentores de bibliotecas, visite LibreOffice Interface de Programação de Aplicações (API) ou descarregue LibreOffice Kit de Desenvolvimento de Software (SDK).

A importação de um módulo incorporado do Python é ilustrada abaixo; o tratamento de exceções não é detalhado:

                import uno, sys, zipimport

                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

Tópicos relacionados

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

Importar módulos Python

Entrada/Saída para o ecrã

Ajuda para os scripts Python no LibreOffice

Necessitamos da sua ajuda!