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.

- Arguments: All keyword arguments passed on to methods are lowercased.

- 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 pretende fazer, você pode escolher uma das seguintes abordagens para executar scripts Python no LibreOffice:

- Executar scripts dentro do processo atual do LibreOffice: Os scripts Python são executados a partir do processo do LibreOffice usando o menu Ferramentas - Macros - Executar Macro ou a extensão APSO para chamar scripts do usuário armazenados na pasta de scripts Python. Você também pode usar o shell Python do APSO para executar scripts Python de forma interativa.

- Executar scripts separadamente do processo LibreOffice: Os scripts Python são executados a partir de um processo externo que se conecta a um processo LibreOffice em execução por meio de um pipe ou um socket.

Se você planeja executar scripts a partir do processo LibreOffice, recomenda-se instalar a extensão APSO (Alternative Script Organizer for Python). No entanto, para desenvolver scripts Python fora do LibreOffice, você pode escolher seu IDE Python preferido.

### Executando scripts a partir do processo LibreOffice

#### Como usar a extensão APSO

A maneira mais fácil de começar a usar scripts em Python no LibreOffice é instalando a extensão APSO. Após a instalação, abra qualquer componente do LibreOffice e acesse Ferramentas - Macros - Organizar scripts Python.

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

Como alternativa, você pode abrir o APSO usando o atalho padrão Alt + Shift + F11.

Agora você pode começar a digitar comandos em Python, e o shell exibirá o resultado correspondente após a execução de cada linha de código.

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

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

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

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

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

#### Criação de arquivos de script em Python

Você pode criar seus próprios arquivos Python e editá-los com o editor de texto de sua preferência. Posteriormente, você poderá chamá-los a partir de qualquer componente LibreOffice.

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

Agora você pode criar um arquivo de texto na pasta de scripts do usuário do Python, por exemplo, my_script.py, e começar a digitar seus scripts.

A seguir, apresentamos um exemplo simples que obtém o valor numérico de uma célula do Calc e o incrementa em 1. Basta digitar o código a seguir no arquivo my_script.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 a função increment_cell. Observe que g_exportedScripts é uma tupla que indica quais funções serão exibidas no LibreOffice como scripts do usuário.

Para executar este script dentro de um documento do Calc:

1. Crie ou abra um arquivo do Calc.

2. Insira um valor numérico na célula "A1" da planilha atual.

3. Acesse Ferramentas - Macros - Executar macros .

4. Selecione Minhas macros - my_script no seletor da biblioteca. Em seguida, selecione a função increment_cell na lista Nome da macro.

5. Clique em Executar. Observe que o valor na célula "A1" foi incrementado em 1.

Você também pode usar o APSO para executar scripts em Python de maneira semelhante:

1. Primeiro, abra o APSO acessando Ferramentas - Macros - Organizar scripts Python.

2. Na lista de macros, acesse Minhas macros - my_script - increment_cell.

3. Clique em Executar.

### Executar scripts separadamente do processo LibreOffice

#### Determinação do caminho de instalação

O primeiro passo para executar scripts em um processo separado é localizar a pasta onde o LibreOffice está instalado. Existem várias maneiras de fazer isso, mas o ScriptForge oferece uma maneira rápida de identificar o caminho 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)

O resultado do código acima é o diretório raiz onde LibreOffice está instalado. Agora, você precisa adicionar a subpasta “program” ao caminho resultante. Essa é a pasta raiz a partir da qual você executará os scripts Python em um processo separado.

Por exemplo, suponha que obtenha /usr/lib/libreoffice/ como resultado da execução do código Python acima. Nesse caso, deve considerar /usr/lib/libreoffice/program como o caminho para executar os seus scripts Python.

#### Inicie o LibreOffice com as configurações pipe ou socket

Para executar scripts Python a partir de um processo separado, é necessário iniciar o LibreOffice com algumas opções adicionais que especifiquem o nome do canal ou o nome do host e a porta através dos quais o processo externo irá comunicar com o processo do componente LibreOffice.

Abra a linha de comandos do seu sistema operacional, acesse a pasta do programa no diretório de instalação LibreOffice e digite uma das seguintes opções:

No Linux ou no macOS:

libreoffice --accept='pipe,name=aPipeName;urp;'

No Windows:

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

como Flatpak:

flatpak run org.libreOffice.LibreOffice accept='socket,host=localhost,port=2021;urp;'

Qualquer um dos comandos acima iniciará o LibreOffice com um canal de comunicação aberto, para que outros processos possam trocar mensagens com ele.

Note que nos exemplos anteriores abrem a tela inicial do LibreOffice. Se desejar abrir um componente específico, por exemplo, o Writer, você pode adicionar a chave --writer ao comando como segue.

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

Tome nota do nome, ou dos parâmetros host e porta, que neste exemplo são aPipeName, ou localhost e 2021, respetivamente.

#### Executar um shell Python externo

Inicie o shell do Python a partir da pasta program dentro do caminho de instalação LibreOffice. Siga os passos acima para saber como localizar o seu caminho de instalação.

No Linux ou no macOS:

$ cd /usr/lib/libreoffice/program

$ python

No Windows:

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

$ python.exe

Isto irá abrir o shell do Python e, a partir daí, poderá começar a introduzir comandos que serão executados pelo LibreOffice. Mas, primeiro, é necessário configurar a conexão pipe ou socket. A instrução ScriptForge() abaixo deve preceder a primeira chamada à função CreateScriptService().

Execute uma das seguintes opções:

       from scriptforge import ScriptForge, CreateScriptService
       ScriptForge(pipe='aPipeName')

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

Leia a seção Definir PYTHONPATH abaixo, caso surjam erros ao importar scriptforge.py ou uno.py.

A segunda linha de código acima define as configurações pipe ou host e port, para que o shell Python possa comunicar com um processo LibreOffice em execução, aberto com as mesmas configurações de pipe ou socket.

Agora pode executar outros comandos Python, que poderão comunicar com o processo LibreOffice. Por exemplo:

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

#### Definir PYTHONPATH

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

Utilize a ferramenta de pesquisa de arquivos do seu sistema operacional para determinar o diretório onde se encontram esses dois arquivos.

Por exemplo, numa 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 destes arquivos varia conforme o sistema operacional e o 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

♥ Doe para nosso projeto! ♥