Sumário

# Criando Scripts Python com o ScriptForge

## Diferenças entre Basic e Python

A biblioteca ScriptForge está disponível nas linguagens Basic e Python. A maioria dos serviços, métodos e propriedades funcionam de forma idêntica em ambas linguagens de programação. Entretanto, devido a diferenças em como cada linguagem funciona, usuários do ScriptForge devem estar cientes de algumas características da biblioteca ao usar Python:

- Nomes de métodos e propriedades: Em Python todos os métodos e propriedades podem ser usados nos formatos lowercased, ProperCased ou camelCased.

- Argumentos: Todos os argumentos de palavra-chave são passados em caixa baixa (lowecased).

- Datas: Todos os objetos de data são passados e retornados como objetos nativos Python do tipo datetime.datetime.

- Arrays: Arrays de uma dimensão são passados e retornados como tuplas (as quais são objetos imutáveis em Python). Arrays de duas dimensões são passados e retornados como tuplas de tuplas.

- None: O objeto None do Python é equivalente às palavras-chave do Basic Null, Empty ou Nothing.

- Objetos UNO: Todas as estruturas UNO são transmitidas entre as linguagens Basic e Python sem mudança alguma.

- Depuração: Sempre que um erro ocorrer em scripts Python que usem a biblioteca ScriptForge, a mensagem de erro fornecida pelo interpretador Python mostrará a linha de código que disparou o erro. Na linguagem Basic as mensagens de erro não possuem essa informação.

Visite a Ajuda dos scripts Python do LibreOffice para maiores informações sobre a criação de scripts Python no LibreOffice.

## Editar scripts Python em IDEs

Dicas de digitação Python - relacionadas a métodos e propriedades públicas de serviços ScriptForge - podem ser obtidas de IDEs que suportam tal recurso. Visualmente, ao editar um script de usuário:

- passar o mouse sobre uma instância de objeto, um método ou uma propriedade exibe sua descrição detalhada.

- um "." depois de uma instância de objeto exibe uma caixa suspensa listando todas as interfaces disponíveis.

- colchetes após o nome de um método iniciam a conclusão do código exibindo seus argumentos.

Dicas de digitação são exibidas ao editar métodos e propriedades com letras maiúsculas e minúsculas.

## Executando scripts Python no LibreOffice

Dependendo do que você deseja fazer, você pode optar por uma das seguintes abordagens para rodar scripts Python no LibreOffice:

- Rodar scripts dentro do processo atual do LibreOffice: Scripts Python são executados de dentro do próprio processo do LibreOffice usando o item de meu Ferramentas - Macros - Executar Macro ou usando a extensão APSO para chamar scripts de usuário armazenados na pasta de scripts Python. Você também pode usar a shell Python da extensão APSO para executar scripts interativamente.

- Executar scripts em processo separado do LibreOffice: Scripts Python são executados a partir de um processo externo que se conecta com um processo em execução do LibreOffice usando um socket.

Se você planeja rodar scripts Pythons dentro do mesmo processo que o LibreOffice, é recomendável instalar a extensão APSO (Alternative Script Organizer for Python) extension. Contudo, para desenvolver scripts Python que serão rodados de fora do LibreOffice, você pode usar sua IDE Python preferida.

## Executando scripts dentro do processo LibreOffice

### Usando a extensão APSO

A maneira mais fácil de começar a criar scripts Python no LibreOffice é instalando a extensão APSO. Após sua instalação, abra qualquer aplicativo do LibreOffice e acesse o item do menu Ferramentas - Macros - Organize python scripts.

Na janela principal do APSO vá em Menu - Python Shell.

Alternativamente você pode abrir a janela principal da extensão APSO usando o atalho padrão Alt + Shift + F11.

Agora você pode começar a digitar comandos em Python e o shell irá imprimir as saídas de cada linha de código ao passo em que são executadas.

Para começar a usar a biblioteca ScriptForge é necessário importar o método CreateScriptService, com o qual você poderá acessar os serviços disponibilizados pela biblioteca. O exemplo abaixo usa o serviço Basic para mostrar uma caixa de mensagem.

        from scriptforge import CreateScriptService
        bas = CreateScriptService("Basic")
        bas.MsgBox("Hello!")

Para executar o exemplo acima, entre cada linha de código no shell Python, uma a uma, pressionando a tecla Enter após digitar cada linha.

Agora você pode começar a executar comandos Python usando qualquer um dos serviços ScriptForge. Por exemplo, o fragmento de código abaixo usa o serviço UI para criar um documento Writer em branco.

        ui = CreateScriptService("UI")
        doc = ui.CreateDocument("Writer")

### Criando arquivos de script em Python

Você pode criar seus próprios arquivos de script em Python e editá-los com seu editor de texto de preferência. Após isso você poderá executá-los a partir de qualquer componente do LibreOffice.

O primeiro passo é localizar onde os scripts de usuário são armazenados. Para isso, consulte a página de ajuda Organização e localização de scripts Python.

Agora você pode criar um arquivo texto dentro da pasta de scripts de usuário em Python, por exemplo sf_test.py, e começar a editar seus próprios scripts.

A seguir é dado um simples exemplo que recupera o valor numérico de uma célula em um documento Calc e incrementa esse valor em uma unidade. Simplesmente escreva o código a seguir no arquivo sf_test.py.

        from scriptforge import CreateScriptService
        doc = CreateScriptService("Calc")

        def increment_cell(args=None):
            value = doc.GetValue("A1")
            value += 1
            doc.SetValue("A1", value)

        g_exportedScripts = (increment_cell, )

Este exemplo cria uma função chamada increment_cell. Note que a tupla g_exportedScripts tem o papel de informar quais funções serão mostradas no LibreOffice como scripts de usuário.

Para executar este script a partir de um documento Calc:

1. Crie ou abra um arquivo Calc.

2. Entre algum valor numérico na célula "A1" da planilha atual.

3. Vá ao menu Ferramentas - Macros - Executar macro .

4. Escolha My Macros - sf_test no seletor de biblioteca. Em seguida, escolha a função increment_cell na lista Nome da macro .

5. Clique em Run. O valor da célula "A1" será incrementado em uma unidade.

Você também pode usar a extensão APSO para rodar scripts Python de maneira similar:

1. Primeiro abra a janela principal da extensão APSO indo em Ferramentas - Macros - Organize python scripts.

2. Na lista de macros, navegue até Minhas macros - sf_test - increment_cell .

3. Clique Execute.

## Executando scripts separadamente do processo LibreOffice

### Determinando o Caminho de Instalação

O primeiro passo para executar passos a partir de um processo separado é encontrar a pasta onde o LibreOffice está instalado. Há várias formas para fazer isso, mas o ScriptForge provê uma maneira rápida de identificar sua pasta de instalação. Para isso, abra o shell Python do APSO e digite:

        from scriptforge import CreateScriptService
        fs = CreateScriptService("FileSystem")
        fs.FileNaming = "SYS"
        inst_dir = fs.InstallFolder
        print(inst_dir)

A saída resultante do código acima é o diretório base onde o LibreOffice está instalado. Agora você precisa adicionar a subpasta "program" ao caminho resultante. Esta será a pasta base a partir da qual você executará scripts Python de um processo separado.

Por exemplo, suponha que você obtenha /usr/lib/libreoffice/ como o resultado após executar o código Python acima. Então você precisa considerar /usr/lib/libreoffice/program como o caminho para executar seus scripts Python.

### Inicializando o LibreOffice com configurações de socket

Para executar scripts em Python de um processo separado, você tem quem inicializar o LibreOffice com alguns parâmetros adicionais para especificar o nome do host (hostname) e a porta (port) pela qual o processo externo irá se comunicar com o processo do componente do LibreOffice.

Abra o terminal de comandos de seu sistema operacional e navegue para o diretório de instalação do LibreOffice e digite:

./soffice --accept='socket,host=localhost,port=2021;urp;'

O comando acima irá inicializar o LibreOffice com um canal de comunicação aberto para que outros processos possam trocar mensagens com ele.

Repare que o exemplo anterior abre o Centro de Partida do LibreOffice. Se você quiser abrir um componente específico, como por exemplo o Writer, você pode adicionar a opção --writer para o comando, conforme o exemplo a seguir:

./soffice --writer --accept='socket,host=localhost,port=2021;urp;'

Anote os valores host e port, os quais neste exemplo são localhost e 2021, respectivamente.

### Executando um Shell Python Externo

Inicialize o shell Python de dentro da pasta program do diretório de instalação do LibreOffice. Siga os passosacima para aprender como encontrar o diretório de instalação.

No Linux / Mac OS:

$ cd /usr/lib/libreoffice/program

$ python

No Windows:

$ cd C:\Program Files\LibreOffice\program\

$ python.exe

Isto abrirá o shell Python e agora você pode começar a digitar comandos que serão executados pelo LibreOffice. Mas primeiro você precisa configurar a conexão de socket.

        from scriptforge import ScriptForge, CreateScriptService
        ScriptForge(hostname='localhost', port=2021)

Leia a seção Configurando o PYTHONPATH abaixo em caso de erros ao importar scriptforge.py ou uno .py.

A segunda linha de código acima define os valores de host e port para que o shell do Python possa se comunicar com um processo LibreOffice em andamento que tenha sido inicializado com as mesmas configurações de socket.

Agora você pode executar outros comandos em Python e eles serão capazes de se comunicar com o processo do LibreOffice. Por exemplo:

        ui = CreateScriptService("UI")
        bas = CreateScriptService("Basic")
        doc = ui.OpenDocument("~/Documents/myFile.ods")
        bas.MsgBox(doc.DocumentType)

### Configurando o PYTHONPATH

Dependendo da configuração do seu sistema operacional você precisará definir a variável de ambiente PYTHONPATH para importar a biblioteca scriptforge.py, que por sua vez requer a importação da biblioteca uno. py.

Use a ferramenta de pesquisa de arquivos do seu sistema operacional para determinar o diretório onde esses dois arquivos estão localizados.

Por exemplo, em uma instalação padrão do Ubuntu, ambos os arquivos podem estar localizados em:

- scriptforge.py: Localizado em /usr/lib/libreoffice/program

- uno.py: Localizado em /usr/lib/python3/dist-packages

Neste caso, defina a variável de ambiente PYTHONPATH da seguinte forma antes de iniciar o interpretador Python:

export PYTHONPATH=/usr/lib/libreoffice/program:/usr/lib/python3/dist-packages

A localização desses arquivos será diferente para cada sistema operacional e método de instalação do LibreOffice.

Tópicos relacionados

A Biblioteca ScriptForge

Ajuda dos scripts Python do LibreOffice

Iniciar o LibreOffice com parâmetros