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.

Python standard output file is not available when running Python macros from Tools - Macros - Run Macro menu. Refer to Input/Output to Screen for more information.

## Importação de módulos

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

LibreOffice Basic libraries contain classes, routines and variables, Python modules contain classes, functions and variables. Common pieces of reusable Python or UNO features must be stored in My macros within (User Profile)/Scripts/python/pythonpath. Python libraries help organize modules in order to prevent module name collisions. Import uno.py inside shared modules.

Genuine BASIC UNO facilities can be inferred using uno.py module. Use Python interactive shell to get a complete module description using dir() and help() Python commands.

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()

LibreLogo, NamedRanges, SetCellColor and TableSample preinstalled scripts use uno.py module.

## 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()
Use "==" or "!=" comparison operators | 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

## Importing an embedded Module

Similarly to LibreOffice Basic that supports browsing and dynamic loading of libraries, Python libraries can be explored and imported on demand. For more information on library containers, visit LibreOffice Application Programming Interface (API) or download LibreOffice Software Development Kit (SDK).

Importing a Python document embedded module is illustrated below, exception handling is not detailed:

                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

Input/Output to Screen

Ajuda para os scripts Python no LibreOffice

Necessitamos da sua ajuda!