Guia de Introdução 24.8
Capítulo 11,
Introdução às macros
Usar o gravador de macro… e além
Este documento é protegido por Copyright © 2025 da Equipe de Documentação do LibreOffice. Os colaboradores estão relacionados abaixo: É permitida a distribuição e/ou modificação sob os termos tanto da GNU General Public License (https://www.gnu.org/licenses/gpl.html), versão 3 ou posterior, ou pela licença Creative Commons Attribution (https://creativecommons.org/licenses/by/4.0/), versão 4.0 ou posterior.
Todas as marcas registradas pertencem a seus proprietários legais.
Rafael Lima, B. Antonio Fernandez, Olivier Hallot, Jackson Cavalcanti Jr.
Jean Hollis Weber, Felipe Viggiano,Kees Kriek, Olivier Hallot, Rafael Lima, Peter Schofield, Andrew Pitonyak, Hazel Russman, Steve Fanning, Martin Fox, Andrew Jensen, Ron Faile Jr., Valerii Goncharuk, Skip Masonsmith, Flywire.
Direcione os comentários ou sugestões sobre este documento para a lista de documentação brasileira: https://community.documentfoundation.org/c/portuguese/documentation/6 (requer registro), ou envie um e-mail para loguides@community.documentfoundation.org.
Nota
Tudo o que enviar para à lista de discussão, incluindo seu endereço de e-mail e qualquer outra informação pessoal escrita na mensagem, fica arquivado publicamente e não pode ser excluído. Os e-mails enviados para o fórum são moderados.
Publicado em julho 2025. Baseado no LibreOffice 24.8 Community.
Outras versões do LibreOffice podem diferir na aparência e funcionalidade.
Alguns pressionamentos de tecla e itens de menu são diferentes no macOS daqueles usados no Windows e Linux. A tabela abaixo fornece algumas substituições comuns para as instruções neste documento. Para uma lista detalhada, consulte a Ajuda do aplicativo.
Windows ou Linux |
Equivalente macOS |
Efeito |
Ferramentas > Opções |
LibreOffice > Preferências |
Acessar as opções de configurações |
Clique com o botão direito |
Ctrl+clique e/ou clique com o botão direito - dependendo da configuração do computador |
Abre um menu de contexto |
Ctrl ou Control |
⌘ (Comando) |
Usado com outras teclas |
Alt |
⌥ (Opcional) ou Alt, dependendo do teclado |
Usado com outras teclas |
F11 |
⌘+T |
Abre o painel de estilos na barra lateral |
Uma macro é um conjunto de comandos ou combinações de teclas que são armazenadas para uso posterior. Por exemplo, uma macro permite entrar um endereço num documento aberto e uma macro pode automatizar tanto tarefas simples como complexas. Macros são muito úteis quando é necessário repetir a mesma tarefa de uma mesma maneira.
A maneira mais simples de criar uma macro é gravar uma série de ações com a interface de usuário do LibreOffice por meio da linguagem de script LibreOffice Basic de código aberto (uma implementação da conhecida linguagem de programação BASIC). Essas macros podem ser editadas e aprimoradas após a gravação com o ambiente de desenvolvimento integrado do LibreOffice Basic.
As macros mais poderosas no LibreOffice podem ser criadas com uma das quatro linguagens de script suportadas: LibreOffice Basic, Python, JavaScript e BeanShell. Este capítulo fornece uma visão geral dos recursos de macro do LibreOffice com ênfase em sua linguagem de script de macro padrão, o LibreOffice Basic. Embora alguns exemplos introdutórios estejam incluídos para as linguagens de script BeanShell, JavaScript e Python, uma discussão aprofundada sobre o uso dessas linguagens para scripts está além do escopo deste capítulo.
Para começar com macros do LibreOffice, recomendamos que encontre e use macros existentes. Assumimos que você tem uma macro existente que deseja usar, que foi originalmente encontrada num livro ou na internet. Neste exemplo, a macro na Listagem 1 é usada. Depois de ter uma macro, você cria uma biblioteca e um módulo para conter sua macro; a criação de uma biblioteca de macros está abaixo, mas consulte “Organização de macros” abaixo para obter mais informações.
Listagem 1: Macro simples que diz olá
Sub HelloMacro
Print "Hello"
End Sub
Utilize as seguintes etapas para criar uma biblioteca que conterá sua macro:
Abra qualquer aplicativo LibreOffice.
Acesse Ferramentas > Macros > Organizar Macros > Basic para abrir a caixa de diálogo Macros Basic (Figura 1).
Clique em Organizador para abrir a caixa de diálogo Organizador de Macros BASIC (Figura 2) e selecione a aba Bibliotecas.
Defina a Localização na lista suspensa Minhas Macros, que é o local padrão.
Clique em Novo para abrir a caixa de diálogo Nova biblioteca (não mostrada aqui).
Figura 1: Caixa de diálogo Macros BASIC
Digite um nome para a biblioteca, por exemplo, TestLibrary, e clique em OK.
Figura 2: Caixa de diálogo Organizador de macros BASIC, aba Bibliotecas
Na caixa de diálogo Organizador Macro BASIC, selecione a guia Módulos (Figura 3).
Figura 3: Caixa de diálogo Organizador de Macros BASIC, aba Módulos
Na lista Módulo, expanda Minhas Macros e selecione sua biblioteca (no exemplo, TestLibrary). Um módulo chamado Module1 já existe e pode receber sua macro. Se desejar, você pode clicar em Novo para criar outro módulo na biblioteca.
Figura 4: Janela do LibreOffice BASIC IDE (Ambiente de Desenvolvimento Integrado)
Selecione Module1, ou o novo módulo que criou, e clique em Editar para abrir o Ambiente de Desenvolvimento Integrado (IDE) (Figura 4). O IDE é um editor de texto com recursos associados incorporados ao LibreOffice e permitem criar, editar, executar e depurar macros.
Quando criar um módulo, ele contém um comentário e uma macro vazia chamada Main, que não faz nada.
Quando pronto, adicione a nova macro antes de Sub Main ou depois de End Sub. A Listagem 2 mostra a nova macro adicionada antes de Sub Main.
Listagem 2: Módulo 1 após adicionar a nova macro
REM ***** BASIC *****
Sub HelloMacro
Print "Hello"
End Sub
Sub Main
End Sub
Dica
Se preferir, você pode remover o código Sub Main… End Sub do Módulo e deixar apenas a sub-rotina HelloMacro.
(Opcional) Para verificar se a macro foi gravada conforme esperado pela linguagem de programação LibreOffice BASIC, clique no ícone Compilar na barra de ferramentas Macro.
Clique duas vezes na sub-rotina HelloMacro na janela Catálogo de objetos em TestLibrary > Módulo 1 e clique no ícone Executar na barra de ferramentas Macro ou pressione a tecla F5 para executar a sub-rotinaHelloMacro no módulo. Abrirá uma pequena caixa de diálogo com a palavra "Hello" exibida (veja abaixo).
Figura 5: Caixa de diálogo com os resultados da instrução Print.
Clique em OK para fechar esta pequena caixa de diálogo.
Se nenhuma sub-rotina ou função for selecionada, abre uma caixa de diálogo como a da Figura 6 . Em seguida, selecione a macro e clique em Executar para executá-la.
Para selecionar e executar qualquer macro no módulo, clique no ícone Selecionar Macro na barra de ferramentas Padrão ou vá para Ferramentas > Macros > Organizar Macros > BASIC.
Selecione uma macro e clique em Executar.
Figura 6: Caixa de diálogo para selecionar e executar uma macro
Ao gravar uma macro no LibreOffice, você está na verdade usando a linguagem de programação para gravar as etapas necessárias para executar uma determinada tarefa. Por exemplo, se tiver que inserir repetidamente as mesmas informações num documento, poderá criar uma macro que insira automaticamente essas informações sem precisar copiá-las sempre que precisar.
Nota
Às vezes, pode ser melhor criar um Autotexto que possa inserir repetidamente informações num documento. Consulte o Capítulo 2, Trabalhar com o Texto: Noções Básicas, no Guia do Writer para obter mais informações.
Primeiro, habilite a gravação de macro no LibreOffice acessando Ferramentas > Opções > LibreOffice > Avançado e selecionando a opção Ativar gravação de macro em Funcionalidades opcionais. Normalmente esse recurso está desativado no LibreOffice.
Acesse Ferramentas > Macros > Gravar macro para começar a gravar uma macro. Aparece uma pequena caixa de diálogo com um botão Parar gravação indicando que o LibreOffice está gravando uma macro.
Digite o texto a inserir ao executar esta macro. Por exemplo, digite seu nome.
Clique em Parar gravação na pequena caixa de diálogo. Isso fará com que a caixa de diálogo Macros Básicas seja aberta (semelhante à Figura 1, mas com diferentes botões de ação).
Encontre a biblioteca chamada Standard em Minhas macros. Observe que cada contêiner de biblioteca tem uma biblioteca chamada Standard.
Selecione a biblioteca Standard e escolha um módulo existente para salvar a macro. Como alternativa, você pode clicar em Novo módulo para criar um módulo para conter a macro recém-gravada.
Na caixa de texto Nome da macro na seção superior esquerda da caixa de diálogo, digite um nome para a macro que acabou de gravar, por exemplo, EnterMyName.
Clique em Salvar para salvar a macro e fechar a caixa de diálogo Macros BASIC.
Se seguiu todas as etapas acima, macro de nome EnterMyName foi criada dentro do módulo selecionado.
Nota
Sempre que criar um módulo no LibreOffice, uma sub-rotina de nome Main é automaticamente adicionada ao módulo.
Acesse Ferramentas > Macros > Executar macro para abrir a caixa de diálogo Seletor de macros (Figura 7).
Por exemplo, selecione sua macro recém-criada EnterMyName e clique em Executar.
Como alternativa, acesse Ferramentas > Macros > Organizar Macros > BASIC para abrir a caixa de diálogo Macros BASIC (Figura 1), selecione sua macro e clique em Executar.
Figura 7: Use a caixa de diálogo Seletor de Macro para selecionar e executar uma macro existente
Para visualizar e editar a macro criada:
Acesse Ferramentas > Macros > Organizar Macros > BASIC para abrir a caixa de diálogo Macros BASIC.
Selecione sua nova macro EnterMyName e clique em Editar. O IDE BASIC será aberto e a macroEnterMyName será mostrada como na Listagem 3.
Esta primeira macro não é complicada (consulte a Listagem 3):
Listagem 3: Código gravado para a macro EnterMyname
sub EnterMyName
rem -------------------------------------------------------------
rem definir variáveis
dim document as object
dim dispatcher as object
rem -------------------------------------------------------------
rem obter acesso ao documento
document = ThisComponent.CurrentController.Frame
dispatcher = createUnoService("com.sun.star.frame.DispatchHelper")
rem -------------------------------------------------------------
dim args1(0) as new com.sun.star.beans.PropertyValue
args1(0).Name = "Text"
args1(0).Value = "Your name"
dispatcher.executeDispatch(document, ".uno:InsertText", "", 0, args1())
end sub
Todos os comentários na codificação e macros BASIC começam com REM, que significa REMark. Todo o texto numa linha que começa com REM é ignorado pelo interpretador BASIC ao executar a macro.
Dica
Você pode usar o caractere de aspa única (') como atalho para iniciar um comentário.
O LibreOffice BASIC não diferencia maiúsculas de minúsculas para palavras-chave, então REM, Rem e rem podem iniciar um comentário. Se você usar constantes simbólicas definidas pela Interface de Programação de Aplicativos (API), é mais seguro assumir que os nomes diferenciam maiúsculas de minúsculas. Vale ressaltar que as constantes simbólicas são um tópico avançado que não é abordado por este guia do usuário e não são necessárias ao usar o gravador de macros no LibreOffice.
Macros individuais são armazenadas em sub-rotinas e essas sub-rotinas começam com a palavra-chave SUB. O final de uma sub-rotina é indicado pelas palavras END SUB. O código começa definindo a sub-rotina chamada Main, que está vazia e não faz nada. Observe que o código na Listagem 3 para a macro EnterMyName começa com a palavra-chave SUB e termina com END SUB.
Existem tópicos avançados que estão além do escopo deste guia do usuário, mas conhecê-los pode ser de interesse:
Você pode escrever sub-rotinas que aceitam valores de entrada a serem usados dentro da macro. Esses valores são chamados de argumentos. Isso só pode ser feito quando criar sub-rotinas do zero. Macros gravadas no LibreOffice não aceitam argumentos.
Outro tipo de sub-rotina é chamada de função, que é uma sub-rotina que pode retornar um valor como resultado de seu processamento. As funções são definidas pela palavra-chave FUNCTION no início. As macros gravadas no LibreOffice criam apenas sub-rotinas.
Ao definir uma variável (que contém dados), você deve usar a palavra-chave DIM, que originalmente significava Dimension e era usada para definir as dimensões de uma matriz. A instrução DIM usada na macro EnterMyName é semelhante a reservar um pedaço de papel para armazenar uma mensagem ou nota.
Na macro EnterMyName, as variáveis document e dispatcher são definidas do tipo object. Outros tipos de variáveis comuns incluem String, Integer e Date. Uma terceira variável, chamada args1, é uma matriz de valores de propriedade. Uma variável do tipo matriz permite que uma única variável contenha vários valores, semelhante ao armazenamento de várias páginas em um único livro. Os valores em uma matriz geralmente começam em zero. O número entre parênteses indica o maior número utilizável para acessar um local de armazenamento. Neste exemplo, há apenas um valor e ele é numerado como zero.
A seguir está uma explicação do código usado na macro EnterMyName.
sub EnterMyName
dim document as object
Nota
Às vezes, usa-se a palavra serviço. Um objeto fornece um serviço quando a macro o aciona por meio de um de seus métodos.
document = ThisComponent.CurrentController.Frame
dispatcher = createUnoService("com.sun.star.frame.DispatchHelper")
dim args1(0) as new com.sun.star.beans.PropertyValue
Nota
Uma explicação da UNO e das estruturas do usuário vai muito além do escopo deste livro. Para obter mais informações sobre como criar e usar estruturas, consulte o sistema de Ajuda do LibreOffice e outros guias BASIC.
args1(0).Name = "Text"
args1(0).Value = "Your name"
dispatcher.executeDispatch(document, ".uno:InsertText", "", 0, args1())
end sub
Ao criar uma macro, é importante fazer duas perguntas antes de gravar:
A tarefa pode ser escrita como um simples conjunto de comandos?
As etapas podem ser organizadas de forma que o comando final da macro deixe o cursor pronto para o próximo comando? Ou permite que o usuário volte a inserir texto ou dados no documento de destino?
Como não é conveniente executar macros repetidamente usando Ferramentas > Macros > Executar Macro, você pode atribuir um atalho de teclado para acioná-la rapidamente. Para atribuir o atalho Ctrl+K à sua macro, faça o seguinte:
Acesse Ferramentas > Personalizar. A caixa de diálogo Personalizar abre.
Selecione a aba Teclado. Na seção Teclas de atalho, selecione o atalho Ctrl+K.
Na seção Categoria, selecione macros do LibreOffice. Navegue nesta seção e selecione a sua macro.
Agora clique no botão Atribuir para atribuir o atalho Ctrl+K à sua macro.
Clique em OK para fechar a caixa de diálogo Personalizar.
Agora você pode executar a sua macro usando o atalho Ctrl+K. Isso é muito rápido e fácil de configurar depois de se acostumar com o fluxo de trabalho de macro. A Figura 8 ilustra as etapas envolvidas.
Figura 8: Atribuir um atalho a uma macro
Infelizmente, o Gravador de Macros não pode registrar algumas ações e suas limitações estão relacionadas à estrutura de despacho do LibreOffice e a sua relação com o gravador de macros.
O objetivo da estrutura de despacho é fornecer acesso uniforme a componentes (documentos) para comandos que geralmente correspondem a itens de menu. Ele traduz Arquivo > Salvar, as teclas de atalho Ctrl+S, ou clica no ícone Salvar na barra de ferramentas Padrão no mesmo "comando de despacho".
Além disso, a estrutura de despacho pode enviar "comandos" de volta para a interface do usuário (UI). Por exemplo, após salvar um novo documento, a estrutura garante que a lista de arquivos recentes seja atualizada.
Um comando de despacho é textual, por exemplo .uno:InsertObject ou .uno:GoToStartOfLine. O comando é enviado para o quadro do documento e para o quadro do comando em torno da API até que seja encontrado um objeto que possa manipular o comando.
O gravador de macros só pode registrar comandos gerados pela estrutura de despacho, mas nem todos os comandos despachados estão completos. Por exemplo, inserir um objeto gera o seguinte código:
dispatcher.executeDispatch(document, ".uno:InsertObject", "", 0, Array())
Não é possível especificar que tipo de objeto criar ou inserir. Se um objeto for inserido a partir de um arquivo, você não poderá especificar qual arquivo inserir.
Se, ao gravar uma macro, você usar Ferramentas > Opções para abrir e modificar itens de configuração, a macro gerada não registrará nenhuma alteração de configuração. Na verdade, o código gerado é comentado para que nem seja executado.
rem dispatcher.executeDispatch(document, ".uno:OptionsTreeDialog", "", 0, Array())
Embora um comando seja gerado quando abrir uma caixa de diálogo, qualquer trabalho feito dentro da caixa de diálogo geralmente não é gravado. Isso ocorre em locais como caixas de diálogo de organização de macro, quando inserir caracteres especiais e tipos semelhantes de caixas de diálogo. Outros possíveis problemas ao usar o gravador de macro podem ocorrer quando inserir uma fórmula, definir dados do usuário, criar filtros no Calc, realizar ações em formulários de banco de dados e exportar um documento para um arquivo PDF criptografado. Você nunca sabe ao certo o que o gravador de macro pode capturar até experimentá-lo. Por exemplo, as ações da caixa de diálogo de pesquisa são capturadas corretamente.
Quando o gravador de macros não é capaz de resolver um problema específico, normalmente o próximo passo é escrever o código real usando os objetos LibreOffice. Infelizmente, há uma curva de aprendizado íngreme para esses objetos do LibreOffice. Geralmente, é melhor começar com exemplos simples e, em seguida, aumentar o escopo das macros à medida que aprender mais. Aprender a ler macros geradas é um bom lugar para começar.
No LibreOffice, as macros são agrupadas em módulos, os módulos são agrupados em bibliotecas e as bibliotecas são agrupadas em contêineres de bibliotecas. Uma biblioteca geralmente é usada como um agrupamento principal para uma categoria inteira de macros ou para um aplicativo inteiro. Os módulos geralmente dividem a funcionalidade, como interação e cálculos do usuário. Macros individuais são sub-rotinas e funções. A Figura 9 mostra um exemplo da estrutura hierárquica das bibliotecas de macros no LibreOffice.
Figura 9: Hierarquia da biblioteca de macros
Acesse Ferramentas > Macros > Organizar Macros > BASIC para abrir a caixa de diálogo Macros BASIC (Figura 1). Todos os contêineres de biblioteca disponíveis são mostrados na lista Macro de e cada documento é um contêiner de biblioteca, capaz de conter várias bibliotecas. O aplicativo em si atua como dois contêineres de biblioteca, um contêiner para macros distribuídas com o LibreOffice chamado Macros da aplicação e um contêiner para macros pessoais chamado Minhas macros.
As Macros da aplicação são armazenadas com o código de tempo de execução do aplicativo, que pode não ser editável por você, a menos que você tenha direitos de administrador no sistema. Isso ajuda a proteger essas macros porque elas não devem ser alteradas e você não deve armazenar suas próprias macros no contêiner Macros da aplicação.
A menos que suas macros sejam aplicáveis apenas a um único documento, elas provavelmente serão armazenadas no contêiner Minhas macros. O contêiner Minhas macros é armazenado em sua área de usuário ou diretório inicial.
Se uma macro estiver contida num documento, uma macro gravada tentará trabalhar nesse documento, porque ela usa principalmente ThisComponent para suas ações.
Cada contêiner de biblioteca contém uma biblioteca chamada Standard. Recomendamos fortemente que crie suas próprias bibliotecas com nomes significativos em vez de usar a biblioteca Standard. Bibliotecas com nomes significativos são mais fáceis de gerenciar e, ao contrário da Standard, suas próprias bibliotecas podem ser importadas para outros contêineres de bibliotecas.
Cuidado
Embora o LibreOffice permita que importe bibliotecas para um contêiner de biblioteca, ele não permitirá que sobrescreva a biblioteca chamada Standard. Portanto, se você armazenar suas macros na biblioteca Standard, não poderá importá-las para outro contêiner da biblioteca.
Assim como faz sentido dar nomes significativos às suas bibliotecas, use nomes significativos para seus módulos. Por padrão, o LibreOffice usa nomes como Module1, Module2 e assim por diante.
Ao criar suas macros, decida onde armazená-las. As macros armazenadas no contêiner da biblioteca de aplicativos chamado Minhas Macros estão disponíveis globalmente para todos os documentos e o armazenamento de uma macro num documento é útil se o documento for compartilhado e você quiser que a macro seja incluída no documento.
Enquanto a biblioteca Standard é carregada automaticamente, outras macros de biblioteca não estão disponíveis até que a biblioteca que as contém seja carregada. Uma biblioteca carregada é exibida de forma diferente de uma biblioteca que não é carregada. Para carregar a biblioteca e os módulos nela contidos, clique duas vezes na biblioteca.
O LibreOffice armazena dados específicos do usuário numa pasta dentro do diretório inicial do usuário. A localização é específica do sistema operacional. Para descobrir onde os dados de configuração estão armazenados, acesse Ferramentas > Opções > LibreOffice > Caminhos. As macros de usuário escritas em BASIC são armazenadas em LibreOffice\4\user\basic. Cada biblioteca é armazenada em seu próprio diretório dentro do diretório basic.
Para uso casual, não é necessário entender onde as macros são armazenadas. Se souber onde elas estão armazenadas, no entanto, poderá criar um backup, compartilhar suas macros ou inspecioná-las se houver um erro.
Se desejar exportar bibliotecas de macros para que elas possam ser reutilizadas e compartilhadas com outras pessoas, use o Organizador de macros do LibreOffice BASIC. Para exportar uma biblioteca de macros:
Acesse Ferramentas > Macros > Organizar Macros > BASIC e clique no botão Organizador.
Clique na aba Bibliotecas e escolha qual biblioteca deseja exportar.
Clique em Exportar e selecione Exportar como biblioteca BASIC (observe que você não pode exportar a biblioteca Standard).
Escolha onde deseja salvar a biblioteca e clique em Salvar.
Ao exportar o uma biblioteca, o LibreOffice cria uma pasta contendo todos os arquivos relacionados à biblioteca. A Figura 10 mostra um exemplo de como uma biblioteca chamada TestLibrary com um único módulo chamado Module1 seria exportada.
Figura 10: Pasta contendo a biblioteca exportada
A caixa de diálogo do LibreOffice BASIC Macro Organizer permite importar bibliotecas de macros para o documento, além de criar, excluir e renomear bibliotecas, módulos e caixas de diálogo.
Na aba Bibliotecas, selecione o contêiner de biblioteca a ser usado e clique em Importar para importar bibliotecas de macros.
Navegue até o diretório que contém a biblioteca a importar (Figura 11). Normalmente, você pode escolher entre dialog.xlb e script.xlb. Não importa qual desses dois arquivos selecionar; ambos permitirão que a sua macro seja importada. As macros podem ser armazenadas em bibliotecas dentro de documentos do LibreOffice. Para importar bibliotecas contidas num documento, selecione um documento em vez de um diretório no disco.
Figura 11: Navegar até uma biblioteca de macros
Selecione um arquivo e clique em Abrir para continuar e abrir a caixa de diálogo Importar Bibliotecas (Figura 12).
Figura 12: Escolha as opções de importação da biblioteca
Selecione as seguintes opções para importar bibliotecas:
Se nenhuma opção for selecionada, a biblioteca será copiada para o diretório de macros do usuário. No entanto, se a biblioteca a importar tiver o mesmo nome e você importar para o mesmo local, ela não será copiada.
Selecione Inserir como referência (somente leitura) se desejar usar a biblioteca como referência, mas não importar essa biblioteca para o documento. Ao usar uma biblioteca como referência, ela permanece em seu local atual e permanece totalmente funcional, mas não pode ser modificada no IDE Básico.
Selecione Substituir bibliotecas existentes se a biblioteca a importar tiver o mesmo nome e quiser substituir a biblioteca existente.
Clique em OK para importar a biblioteca de macros selecionada.
Nota
Você não pode exportar/importar a biblioteca chamada Standard.
Dica
No Linux, os arquivos específicos do LibreOffice são armazenados no diretório home do usuário dentro da pasta .config. Diretórios e arquivos com nomes que começam com um ponto podem ser ocultados e não mostrados numa caixa de diálogo de seleção de arquivo normal. Ao usar as caixas de diálogo do LibreOffice, em vez das caixas de diálogo específicas do sistema operacional, digite o nome do diretório desejado no campo Nome.
Você pode encontrar macros criadas pela comunidade do LibreOffice na internet. Algumas macros estão contidas em documentos, algumas como arquivos regulares a importar e outras são publicadas como texto e devem ser copiadas e coladas no IDE BASIC. Consulte “Adicionando uma macro” acima sobre como adicionar macros à sua biblioteca de macros e “Visualizar e editar macros” acima sobre como editar macros usando o IDE BASIC.
Algumas macros estão disponíveis como downloads gratuitos na Internet (consulte a Tabela Tabela 1).
Tabela 1. Locais para encontrar exemplos de macro
Localização |
Descrição |
Materiais de referência sobre macros. |
|
Materiais de referência sobre macros de banco de dados. |
|
Muitos links para macros. |
|
Fóruns, com muitos exemplos e ajuda. |
Você pode executar uma macro com Ferramentas > Macros > Executar, mas isso não será eficiente se usar macros com frequência. Felizmente, o LibreOffice tem muitas outras maneiras de executar suas macros.
Embora possa atribuir um atalho para macros, como visto em "Executar uma macro" acima, você também pode vincular macros a um ícone de barra de ferramentas, item de menu, evento ou um botão incorporado num documento. Ao escolher um método, também é bom fazer perguntas como:
A macro deve estar disponível para apenas um documento ou globalmente para todos os documentos?
A macro é para um tipo de documento específico, como um documento do Calc?
Com que frequência a macro será usada?
As respostas determinarão onde armazenar a macro e como disponibilizá-la. Por exemplo, você provavelmente não adicionará uma macro raramente usada a uma barra de ferramentas. Para ajudar a determinar suas escolhas, consulte a Tabela Tabela 2.
Tabela 2. Onde armazenar uma macro
Onde colocar a macro |
Para todos os aplicativos LibreOffice |
Para uma aplicação LibreOffice específica |
Para um único documento |
Barras de ferramentas |
Não |
Sim |
Sim |
Menu |
Não |
Sim |
Sim |
Atalho |
Sim |
Sim |
Não |
Evento |
Sim |
Não |
Sim |
Para adicionar um item de menu, atalho de teclado ou ícone de barra de ferramentas que chame uma macro, use a caixa de diálogo Personalizar, que permite configurar menus, atalhos de teclado, barras de ferramentas e eventos. Para abrir esta caixa de diálogo, acesse Ferramentas > Personalizar. O uso das abas Menus, Barras de Ferramentas, Menus de Contexto e Teclado são abordados no Capítulo 13, Personalizar o LibreOffice.
Sempre que o LibreOffice detecta uma ação do usuário, chamamos isso de evento. Por exemplo, abrir um documento, alterar o status de modificado ou mover o cursor do mouse são todos eventos. O LibreOffice permite que eventos acionem a execução de uma macro; a macro é então chamada de manipulador de eventos. A cobertura completa dos manipuladores de eventos está muito além do escopo deste capítulo, mas um pouco de conhecimento pode realizar muito.
Cuidado
Tenha cuidado ao configurar um manipulador de eventos. Por exemplo, se escrever um manipulador de eventos que é chamado toda vez que um documento é modificado, mas comete um erro para que o evento não seja tratado adequadamente, podem ocorrer problemas. Um resultado possível é que seu manipulador de eventos o forçará a fechar o LibreOffice.
Acesse Ferramentas > Personalizar para abrir a caixa de diálogo Personalizar e selecione a aba Eventos (Figura 13). Os eventos na caixa de diálogo Personalizar estão relacionados a todo o aplicativo e a documentos específicos.
No menu suspenso Salvar em, selecione LibreOffice ou um documento específico no menu para salvar seu evento.
Um uso comum é atribuir o evento Ao abrir documento para chamar uma macro específica. A macro então executa determinadas tarefas de configuração para o documento. Selecione o evento desejado e clique em Macro para abrir a caixa de diálogo Seletor de Macro (semelhante à Figura 7 , mas com diferentes botões de ação).
Selecione a macro desejada e clique em OK para atribuir a macro ao evento. A aba Eventos mostrará que o evento foi atribuído a uma macro.
Muitos objetos num documento podem ser definidos para chamar macros quando ocorrem eventos. O uso mais comum é adicionar um controle, como um botão, ao documento. Mesmo clicando duas vezes numa figura abre uma caixa de diálogo com uma aba Macros que permite atribuir uma macro a um evento.
Figura 13: Aba Eventos na caixa de diálogo Personalizar
Uma extensão é um código que pode ser instalado no LibreOffice para adicionar novas funcionalidades. As extensões podem ser escritas em quase qualquer linguagem de programação e podem ser simples ou sofisticadas. As extensões podem ser agrupadas em tipos, por exemplo:
Suplementos do Calc, que fornecem novas funcionalidades para o Calc, incluindo novas funções que funcionam como funções internas normais.
Novos componentes e funcionalidades, que normalmente incluem algum nível de integração da Interface do Usuário (UI), como novos menus ou barras de ferramentas.
Suplementos de gráfico com novos tipos de gráfico.
Componentes linguísticos, como verificadores ortográficos.
Modelos e imagens de documentos.
Embora extensões individuais possam ser encontradas em vários lugares, atualmente existe um repositório de extensões em: https://extensions.libreoffice.org/ e alguma documentação em https://libreplanet.org/wiki/Group:OpenOfficeExtensions/List.
Para obter mais informações sobre como obter e instalar extensões, consulte o Capítulo 13, Personalizar o LibreOffice.
Os exemplos abordados até agora neste capítulo foram criados usando o gravador de macros e o dispatcher, mas você também pode escrever macros em código que acessam diretamente os objetos que compõem o LibreOffice. Em outras palavras, você pode criar uma macro que manipula diretamente um documento usando uma lógica de programação mais avançada.
Manipular diretamente objetos internos do LibreOffice é um tópico avançado que está além do escopo deste capítulo. Um exemplo simples, no entanto, demonstra como isso funciona.
O código de exemplo na Listagem 4 é um exemplo simples de uma macro criada sem o gravador que adiciona a cadeia de caracteres "Hello" no final de um documento do Writer.
Para adicionar esta macro a uma biblioteca, siga as etapas abaixo:
Acesse Ferramentas > Macros > Organizar Macros > BASIC.
Em Minhas Macros, navegue até a biblioteca onde deseja que a macro seja criada. Neste exemplo, considere a biblioteca TestLibrary.
Selecione um dos módulos já disponíveis na biblioteca, por exemplo Module1. Se quiser criar um módulo, clique em Organizador e adicione o novo módulo.
Com o módulo selecionado, clique em Editar. Isso abrirá a janela do IDE BASIC e mostrará o código das macros implementadas no módulo selecionado.
Insira o código na Listagem 4 no módulo.
Listagem 4: Anexe o texto "Hello" no final do documento atual
Sub AppendHello
Dim oDoc
Dim sTextService$
Dim oCurs
REM ThisComponent refere-se ao documento atualmente ativo.
oDoc = ThisComponent
REM Verifique se este é um documento de texto.
sTextService = "com.sun.star.text.TextDocument"
If NOT oDoc.supportsService(sTextService) Then
MsgBox "Esta macro só funciona com um documento de texto"
Exit Sub
End If
REM Obtenha o cursor visual do controlador atual.
oCurs = oDoc.currentController.getViewCursor()
REM Mova o cursor para o final do documento.
oCurs.gotoEnd(False)
REM Insert text "Hello" at the end of the document.
oCurs.Text.insertString(oCurs, "Hello", False)
End Sub
Uma maneira poderosa de estender as funcionalidades do LibreOffice Calc é escrever macros que automatizem tarefas repetitivas. Você pode usar a linguagem BASIC para escrever macros que podem realizar tarefas que vão desde o simples manuseio e formatação de células até a manipulação avançada de dados.
Por exemplo, a Listagem 5 abaixo mostra o código BASIC para uma macro que analisa um intervalo de células para determinar se todos os valores estão entre 0 e 100. Os valores que variam de 50 a 100 devem ser marcados em verde-claro, enquanto as células com valores maiores ou iguais a 0 e menores que 50 devem ser marcadas em vermelho claro. Se algum valor fora do intervalo permitido de 0 a 100 for encontrado, uma mensagem de aviso deve ser exibida e as células devem ser marcadas em cinza claro.
Listagem 5: macro do Calc para formatar intervalos com base em valores
Sub FormatRangeBasedOnValue
'Obtém a seleção atual
Dim oRange as Object, oCell as Object
Set oRange = Thiscomponent.getCurrentSelection()
'Verifica se o intervalo selecionado é um intervalo único
If Not oRange.supportsService("com.sun.star.sheet.SheetCellRange") Then
MsgBox "Esta macro se aplica apenas a intervalos únicos."
Exit Sub
End If
' Número de colunas e linhas na seleção
Dim nCols as Long : nCols = oRange.Columns.getCount()
Dim nRows as Long : nRows = oRange.Rows.getCount()
Dim col as Long, row as Long
Dim cellValue as Long
Dim isError as Boolean : isError = False
' Iterar sobre todas as células no intervalo
For col = 0 To nCols - 1
For row = 0 to nRows - 1
Set oCell = oRange.getCellByPosition(col, row)
cellValue = oCell.getValue()
If cellValue >= 50 and cellValue <= 100 Then
' Define o fundo para verde claro
oCell.CellBackcolor = RGB(144, 238, 144)
ElseIf cellValue >= 0 and cellValue < 50 Then
' Define o fundo para vermelho claro
oCell.CellBackcolor = RGB(255, 127, 127)
Else
' Define o fundo para cinza claro
oCell.CellBackcolor = RGB(220, 220, 220)
isError = True
End If
Next row
Next col
' Exibe uma mensagem indicando que houve erros
If isError Then
MsgBox "Algumas células fora do intervalo de 0 a 100 foram marcadas em cinza claro"
End If
End Sub
Para adicionar esta macro a uma biblioteca, siga as etapas descritas em "Um exemplo de uma macro no código para o Writer" acima. Para executar esta macro, primeiro crie uma nova planilha e adicione alguns valores numéricos num intervalo de células. Em seguida, selecione as células e use um dos métodos descritos em “Como executar uma macro” acima para executá-la.
A Figura 14 mostra um exemplo da macro sendo executada num conjunto de células. Como algumas das células têm valores que não estão entre 0 e 100, a caixa de mensagem na Figura 15 também será exibida.
Figura 14: Valores das células após serem formatadas pela macro
Figura 15: Caixa de mensagem apresentada se alguns valores não estiverem entre 0 e 100
Como os programadores de macros frequentemente precisam executar tarefas como criar e abrir arquivos, acessar controles de formulário, ler dados de bancos de dados incorporados em documentos Base e assim por diante, o LibreOffice fornece a eles a biblioteca ScriptForge. Esta biblioteca facilita a execução de tais comandos sem ter que aprender as APIs (Interfaces de Programação de Aplicativos) e comandos necessários do LibreOffice, o que pode ser difícil para programadores casuais.
O ScriptForge é organizado num conjunto de serviços, cada um dos quais fornece métodos e propriedades relacionados a um tópico específico. Por exemplo, o serviço Dialog fornece acesso a caixas de diálogo disponíveis em módulos de script e o serviço Database permite executar comandos SQL em documentos do Base. O exemplo na Listagem 6 mostra uma macro escrita em BASIC usando a biblioteca ScriptForge que abre um documento Calc, cria uma nova folha chamada NewSheet e insere a cadeia de caracteres "Hello" na célula A1. A macro também salva e fecha o documento.
Listagem 6: Macro usando a biblioteca ScriptForge
Sub CreateSheetExample
' Carrega a biblioteca do ScriptForge
GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
' Instancia o serviço de interface de usuário
Dim ui as Object, myDoc as Object
ui = CreateScriptService("UI")
' Abre o arquivo "myfile.ods"
Set myDoc = ui.OpenDocument("/home/user/Documents/myfile.ods")
' Insere uma nova planilha chamada "NewSheet"
myDoc.InsertSheet("NewSheet")
' Insere a string "Hello" na célula "A1" da nova planilha
myDoc.SetValue("NewSheet.A1", "Hello")
' Mostra a planilha "NewSheet"
myDoc.Activate("NewSheet")
' Salva o documento
myDoc.Save()
' Fecha o documento
myDoc.CloseDocument()
End Sub
Como visto no exemplo, a biblioteca ScriptForge fornece comandos diretos para executar comandos e simplificar a criação de macros.
Dica
Para saber mais sobre a biblioteca ScriptForge, visite a Ajuda online do LibreOffice em https://help.libreoffice.org/24.8/pt-BR/text/sbasic/shared/03/lib_ScriptForge.html?DbPAR=BASIC. Cada um dos 26 serviços suportados foi amplamente documentado e exemplos são fornecidos para as linguagens de programação BASIC e Python.
O LibreOffice possui uma extensa API que pode ser usada por programadores de macro para automatizar quase qualquer aspecto de seus aplicativos. No entanto, os programadores geralmente têm problemas para descobrir tipos de objetos, bem como seus serviços, métodos e propriedades suportados.
O modelo de componente usado no LibreOffice é conhecido como Universal Network Objects ou UNO. As macros do LibreOffice em qualquer linguagem de script usam uma interface de programação de aplicativo (API) de tempo de execução UNO. A interface XSCRIPTCONTEXT é fornecida para scripts de macro em todas as quatro linguagens disponíveis (LibreOffice Basic, Python, JavaScript e BeanShell), e fornece alguns meios de acesso às várias interfaces que podem ser necessárias para executar uma ação num documento.
O Uno Object Inspector pode ajudar os desenvolvedores de macros a inspecionar objetos, aprender como acessá-los e usá-los em macros. Este recurso está disponível no Writer, Calc, Impress e Draw. Para habilitá-lo, vá para Ferramentas > Ferramentas de Desenvolvimento. O Inspetor de Objetos será aberto na parte inferior da interface do usuário, conforme mostrado na Figura 16.
A parte esquerda do Inspetor de Objetos consiste no navegador Document Object Model (DOM), permitindo ao usuário navegar por todos os objetos do documento. Ao selecionar um objeto, as informações sobre o objeto são mostradas na parte direita da janela do Inspetor de Objetos:
Os nomes de todas as interfaces implementadas.
Os nomes de todos os serviços suportados pelo objeto.
Os nomes e tipos de todas as propriedades disponíveis no objeto.
Os nomes, argumentos e tipos de retorno de todos os métodos que podem ser chamados pelo objeto.
Figura 16: Inspetor de Objetos UNO aberto em um documento do Writer
Em vez de inspecionar objetos usando o navegador DOM, é possível inspecionar diretamente o objeto atualmente selecionado no documento alternando o botão Seleção atual.
Por exemplo, suponha que queira alterar a cor de fundo do texto selecionado num documento do Writer. Você pode selecionar uma parte do texto, abrir o Inspetor de Objetos, alternar o botão Seleção Atual e inspecionar as propriedades do objeto em busca de uma propriedade que corresponda ao efeito desejado. A Figura 17 mostra a propriedade CharBackColor selecionada, que é a propriedade usada para definir a cor de fundo do texto.
Figura 17: Usando o Inspetor de Objetos para encontrar uma propriedade
Agora é possível escrever uma macro usando esta propriedade para alterar a cor de fundo do texto selecionado. A Listagem 7 mostra o código para esta macro.
Listagem 7: Macro que altera a cor de fundo de um intervalo de texto
Sub ChangeTextBGColor
Dim oSel as Object
Set oSel = ThisComponent.getCurrentSelection()
oSel(0).CharBackColor = RGB(255, 127, 127)
End Sub
Observe que no Writer é possível ter vários intervalos selecionados de uma só vez, portanto, oSel(0) acessa o primeiro intervalo de texto.
Muitos programadores podem não estar familiarizados com o LibreOffice BASIC, então o LibreOffice suporta macros escritas em três outras linguagens familiares: Python, BeanShell e JavaScript.
As macros são organizadas da mesma maneira para todas as quatro linguagens de script. O contêiner de Macros do LibreOffice contém todas as macros que são fornecidas na instalação do LibreOffice. O contêiner da biblioteca Minhas Macros contém as macros que você disponibilizou para qualquer um dos seus documentos do LibreOffice. Cada documento também pode conter suas macros que não estão disponíveis para nenhum outro documento.
Quando usar o recurso de gravação, as macros são criadas no LibreOffice BASIC. Para usar as outras linguagens de script disponíveis, você mesmo deve escrever o código.
Quando escolher executar uma macro usando Ferramentas > Macros > Executar Macro, o LibreOffice exibe a caixa de diálogo Seletor de Macros. Esta caixa de diálogo permite a seleção e execução de qualquer macro disponível, codificada em qualquer uma das linguagens disponíveis (Figura 18).
Ao editar uma macro usando Ferramentas > Macros > Editar Macros, o LibreOffice exibe o IDE do LibreOffice BASIC. Esta caixa de diálogo permite a seleção e edição de qualquer macro disponível do LibreOffice BASIC, mas não de macros em outras linguagens.
Figura 18: Caixa de diálogo Seletor de macro
Dica
Se quiser saber mais sobre a API do LibreOffice e os objetos UNO, consulte a documentação oficial da API em https://api.libreoffice.org/
Python é uma linguagem de programação de alto nível e de uso geral que foi lançada pela primeira vez em 1991.
Ao selecionar Ferramentas > Macros > Organizar Macros > Python, o LibreOffice exibe a caixa de diálogo Macros Python (Figura 19). No momento, os recursos para editar e depurar scripts Python não estão integrados à interface de usuário padrão do LibreOffice. No entanto, você pode usar qualquer editor Python para criar scripts e, em seguida, copiar esses arquivos para a pasta Scripts em seu diretório inicial. Para obter mais informações, consulte “Onde são armazenadas as macros ?” acima.
Figura 19: Caixa de diálogo Macros Python
A Listagem 8 apresenta um exemplo de uma macro Python que escreve o texto “Hello World from Python” na célula A1 da primeira planilha numa planilha do Calc.
Listagem 8: Exemplo de macro do Python
import uno
def HelloWorld():
doc = XSCRIPTCONTEXT.getDocument()
cell = doc.Sheets[0]['A1']
cell.setString('Hello World from Python')
return
Dica
A extensão Alternative Python Script Organizer (APSO) facilita a edição e organização de scripts Python, especialmente quando são incorporados num documento. Usando o APSO, você pode configurar seu editor de código-fonte preferido, iniciar o shell Python integrado e depurar scripts Python. Visite https://gitlab.com/jmzambon/apso para baixar o APSO e saber mais sobre como usá-lo.
Dica
Para saber mais sobre scripts Python no LibreOffice, você pode consultar o Wiki “Macros/Python Basics”, onde encontrará explicações detalhadas e exemplos de como começar a usar scripts Python. Para saber mais, visite https://wiki.documentfoundation.org/Macros/Python_Basics.
O BeanShell é uma linguagem de script semelhante ao Java que foi lançada pela primeira vez em 1999.
Ao selecionar Ferramentas > Macros > Organizar Macros > BeanShell, o LibreOffice exibe a caixa de diálogo Macros do BeanShell (Figura 20).
Figura 20: Caixa de diálogo Macros do BeanShell
Clique no botão Editar na caixa de diálogo Macros do BeanShell para acessar a Janela de Depuração do BeanShell (Figura 21).
Figura 21: Janela de depuração do BeanShell
A listagem 9 é um exemplo de uma macro do BeanShell que insere o texto "Hello World do BeanShell" na célula A1 da planilha Calc ativa.
Listagem 9: Exemplo de macro do BeanShell
import com.sun.star.uno.UnoRuntime;
import com.sun.star.sheet.XspreadsheetView;
import com.sun.star.text.XText;
model = XSCRIPTCONTEXT.getDocument();
controller = model.getCurrentController();
view = UnoRuntime.queryInterface(XSpreadsheetView.class, controller);
sheet = view.getActiveSheet();
cell = sheet.getCellByPosition(0, 0);
cellText = UnoRuntime.queryInterface(XText.class, cell);
textCursor = cellText.createTextCursor();
cellText.insertString(textCursor, "Hello World from BeanShell", true);
return 0;
JavaScript é uma linguagem de script de alto nível que foi lançada pela primeira vez em 1995.
Ao selecionar Ferramentas > Macros > Organizar Macros > JavaScript, o LibreOffice exibe a caixa de diálogo Macros JavaScript (Figura 22).
Figura 22: Caixa de diálogo Macros JavaScript
A listagem 10 é um exemplo de uma macro JavaScript que insere o texto "Hello World from JavaScript" na célula A1 da primeira folha numa planilha do Calc.
Listagem 10: Exemplo de macro JavaScript
importClass(Packages.com.sun.star.uno.UnoRuntime);
importClass(Packages.com.sun.star.sheet.XspreadsheetDocument);
importClass(Packages.com.sun.star.container.XindexAccess);
importClass(Packages.com.sun.star.table.XcellRange);
importClass(Packages.com.sun.star.table.Xcell);
documentRef = XSCRIPTCONTEXT.getDocument();
spreadsheetInterface = UnoRuntime.queryInterface(XSpreadsheetDocument, documentRef);
allSheets = UnoRuntime.queryInterface(XIndexAccess, spreadsheetInterface.getSheets());
theSheet = allSheets.getByIndex(0);
Cells = UnoRuntime.queryInterface(XCellRange,theSheet);
cellA1 = Cells.getCellByPosition(0,0);
theCell = UnoRuntime.queryInterface(XCell,cellA1);
theCell.setFormula("Hello World from JavaScript");
Para alterar o esquema de cores usado pelo editor de código IDE BASIC, siga as seguintes etapas:
A partir do IDE BASIC, acesse Exibir > Esquema de cores para abrir a caixa de diálogo Esquema de cores.
A opção Usar Cores do Aplicativo selecionada é o padrão, o que faz com que o IDE BASIC use as cores definidas na caixa de diálogo Cores do Aplicativo (acessível via Ferramentas > Opções > Cores do Aplicativo)
Para usar um esquema de cores diferente, clique em Escolher esquema de cores e selecione uma das entradas disponíveis na lista suspensa.
Clique em OK para aplicar o esquema de cores selecionado.
A Figura 23 mostra o editor de código após selecionar o esquema de cores Luz Solarizada. Observe que o esquema de cores altera apenas as cores usadas pelo editor de código.
Figura 23: IDE BASIC após a aplicação do esquema de cores Luz Solarizada
Dica
Esquemas de cores adicionais podem ser adicionados por extensões. Visite o site de Extensões do LibreOffice para procurar esquemas de cores adicionais para o seu IDE BASIC.
Inúmeros recursos estão disponíveis que fornecem ajuda para escrever macros. Use Ajuda > Ajuda do LibreOffice ou pressione a tecla F1 para abrir as páginas de ajuda do LibreOffice. O canto superior esquerdo do sistema de ajuda do LibreOffice contém uma lista suspensa que determina qual conjunto de ajuda é exibido. Para visualizar a ajuda do BASIC, escolha BASIC nesta lista.
Muitas macros excelentes estão incluídas no LibreOffice. Use Ferramentas > Macros > Organizar Macros > BASIC para abrir a caixa de diálogo Macros do LibreOffice BASIC. Expanda a biblioteca Ferramentas no contêiner da biblioteca LibreOffice. Inspecione o módulo Debug; alguns bons exemplos incluem WritedbgInfo (documento) e printdbgInfo (folha).
Os seguintes links e referências contêm informações sobre programação de macro:
https://wiki.documentfoundation.org/Macros
https://ask.libreoffice.org/ (um site de perguntas e respostas onde voluntários respondem a perguntas relacionadas ao LibreOffice)
https://wiki.documentfoundation.org/Documentation/Other_Documentation_and_Resources (consulte a seção Programadores para obter o Guia do Programador BASIC e o Guia do Desenvolvedor; o último contém uma explicação detalhada)
http://forum.openoffice.org/en/forum/ (fórum da comunidade Apache OpenOffice; voluntários também respondem a perguntas sobre o LibreOffice)
Andrew Pitonyak publicou um livro online gratuito OpenOffice.org Macros Explained, que é uma ótima referência para aprender a linguagem BASIC usada no LibreOffice e no OpenOffice. Você pode baixar a versão em PDF em https://www.pitonyak.org/OOME_3_0.pdf.
O Dr. Mark Alexander Bain publicou o livro Learn OpenOffice.org Spreadsheet Macro Programming. Consulte https://www.packtpub.com/openoffice-ooobasic-calc-automation/book.
A Programação de Banco de Dados com OpenOffice.org Base & Basic de Roberto Benitez também é uma ótima fonte para aprender mais sobre programação macro.