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:

tip

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


Executando scripts Python no LibreOfficeDev

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

tip

Se você planeja rodar scripts Pythons dentro do mesmo processo que o LibreOfficeDev, é 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 LibreOfficeDev, você pode usar sua IDE Python preferida.


Executando scripts dentro do processo LibreOfficeDev

Usando a extensão APSO

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

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

tip

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 LibreOfficeDev.

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 LibreOfficeDev 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 LibreOfficeDev

Determinando o Caminho de Instalação

O primeiro passo para executar passos a partir de um processo separado é encontrar a pasta onde o LibreOfficeDev 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 LibreOfficeDev 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 LibreOfficeDev com configurações de socket

Para executar scripts em Python de um processo separado, você tem quem inicializar o LibreOfficeDev 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 LibreOfficeDev.

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

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

O comando acima irá inicializar o LibreOfficeDev 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 LibreOfficeDev. 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 LibreOfficeDev. 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 LibreOfficeDev. Mas primeiro você precisa configurar a conexão de socket.


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

Read the section Setting PYTHONPATH below in case of errors importing scriptforge.py or 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 LibreOfficeDev 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 LibreOfficeDev. Por exemplo:


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

Setting PYTHONPATH

Depending on your operating system's configuration you will need to set the environment variable PYTHONPATH in order to import the scriptforge.py library, which in turn requires importing the uno.py library.

Use your operating system's file search tool to determine the directory where both these files are located.

For instance, on a default Ubuntu installation both files may be located at:

In this case, set the environment variable PYTHONPATH as follows before starting the Python interpreter:

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

note

The location of these files will be different for each operating system and LibreOfficeDev installation method.