Guia do Calc 7.0

Capítulo 12
Macros

Automatizar tarefas repetitivas

Introdução

O Capítulo 13 do Guia do Iniciante (intitulado Primeiros passos com macros ) é uma introdução aos recursos de macro disponíveis no LibreOffice. O capítulo atual apresenta mais informações introdutórias sobre o uso de macros numa planilha do Calc.

Uma macro é um conjunto de comandos ou pressionamentos de tecla que são armazenados para uso posterior. Um exemplo de macro simples é aquela que insere seu endereço na célula atual de uma planilha aberta. Você pode usar macros para automatizar tarefas simples e complexas e elas permitem que você introduza novos recursos que não são integrados ao Calc.

A maneira mais simples de criar uma macro é registrar uma série de ações por meio da interface de usuário do Calc. O Calc salva macros gravadas usando a linguagem de script LibreOffice Basic de código aberto, que é um dialeto da conhecida linguagem de programação BASIC. Essas macros podem ser editadas e aprimoradas após a gravação usando o ambiente integrado de desenvolvimento (IDE) do LibreOffice Basic.

Macros mais poderosas no Calc são criadas escrevendo código em uma das quatro linguagens de script suportadas (LibreOffice Basic, BeanShell, JavaScript e Python). Este capítulo fornece uma visão geral dos recursos de macro do Calc, principalmente focados em sua linguagem de script de macro padrão, o LibreOffice Basic. Alguns exemplos estão incluídos para as linguagens de script BeanShell, JavaScript e Python, mas descrições mais completas dos recursos para essas linguagens estão além do escopo deste documento.

Sobre compatibilidade do Visual Basic for Application (VBA)

A linguagem de programação LibreOffice BASIC e a linguagem de programação VBA – encontradas em muitos documentos do Microsoft Office, incluindo planilhas do Excel – são dialetos da linguagem BASIC. Se desejar usar macros escritas no Microsoft Excel no LibreOffice, você deve primeiro editar o código no editor IDE do LibreOffice Basic.

Alguns elementos para a conversão de macros do Excel escritas em VBA são detalhados no final deste capítulo.

Utilizar o gravador de macro

O Capítulo 13 do Guia do Iniciante inclui exemplos que mostram como usar o gravador de macro e entender os scripts do LibreOffice Basic gerados. As etapas a seguir fornecem um exemplo adicional, específico para uma planilha do Calc, sem as explicações mais detalhadas do Guia do Iniciante. Criaremos uma macro com o comando Colar especial com uma multiplicação num intervalo de células da planilha.

Nota

Acesse o menu Ferramentas > Opções > LibreOffice > Avançado na barra de menu e selecione a opção Ativar gravação de macro (recursos com limitações) para habilitar o gravador de macro.

1. Utilize Arquivo > Novo > Planilha na barra de menus para criar uma planilha.

2. Insira os números mostrados na Figura 1 nas células A1: C3 na Planilha1 na nova planilha.

1. Selecione a célula A3, que contém o número 3, e use Editar > Copiar na barra de menus para copiar o valor para a área de transferência.

2. Selecione todas as células no intervalo A1:C3.

3. Utilize Ferramentas > Macros > Gravar macro na barra de menus para iniciar o gravador de macro. O Calc exibe a caixa de diálogo Gravar Macro, que inclui um botão Parar gravação (Figura 2)

1. Utilize Editar > Colar especial > Colar especial na barra de menus para abrir a caixa de diálogo Colar especial (Figura 3):

1. Selecione a opção Colar tudo na área Seleção e a opção Multiplicar na área Operações e clique em OK. Os valores nas células A1: C3 agora são multiplicados por 3 (Figura 4)

1. Clique no botão Parar gravação para parar o gravador de macro. O Calc exibe uma variante da caixa de diálogo Macros Basic (Figura 5).

Nota

A área Salvar macro em da caixa de diálogo Macros Basic mostra as macros existentes do LibreOffice Basic, hierarquicamente estruturadas em contêineres de biblioteca, bibliotecas, módulos e macros, conforme descrito no Capítulo 13 do Guia do Iniciante. A Figura 5 mostra o contêiner de biblioteca Minhas Macros, o contêiner de biblioteca Macros do LibreOffice, o contêiner de biblioteca para o arquivo aberto balance.ods e o contêiner de biblioteca para o arquivo Sem Título criado na etapa 1. Utilize os ícones expandir / recolher à esquerda do nome de cada contêiner de biblioteca para visualizar as bibliotecas, módulos e macros dentro desse contêiner.

1. Selecione a entrada para o documento atual na área Salvar macro em. Como o documento atual neste exemplo não foi salvo, ele é referido por seu nome padrão Sem título 1.

2. Os documentos que foram salvos incluem uma biblioteca de macros chamada Standard. Esta biblioteca não é criada até que o documento seja salvo ou a biblioteca seja necessária, portanto, neste ponto do procedimento de exemplo, seu novo documento não contém uma biblioteca. Você pode criar uma biblioteca para conter a macro que acabou de criar, mas isso não é necessário.

3. Clique no botão Novo módulo. O Calc exibe a caixa de diálogo Novo módulo (Figura 6) Digite um nome para o novo módulo ou deixe o nome como padrão Módulo 1.

Nota

As bibliotecas, módulos e nomes de macro devem seguir algumas regras rígidas. Seguindo as principais regras, os nomes devem:

Inclui letras minúsculas (a..z), letras maiúsculas (A..Z), dígitos (0..9) e caracteres de sublinhado (_)

Comece com uma carta ou um sublinhado

Não conter quaisquer outros espaços, símbolos de pontuação ou caracteres especiais (incluindo acentos)

1. Clique no botão OK botão para criar um módulo. Como nenhuma biblioteca de macro existe em nosso documento atual, o Calc cria e usa automaticamente uma biblioteca Standard.

2. Na caixa de diálogo Macros Basic, selecione a entrada para o módulo recém-criado na área Salvar macro em, digite o texto PasteMultiply no Nome da macro e clique no botão Salvar (Figura 7).

A macro é salva com o nome PasteMultiply no módulo recém-criado dentro da biblioteca Standard do documento Sem título 1. A Listagem 1 mostra o conteúdo da macro.

Listagem 1. Colar especial com a macro multiplicar

sub PasteMultiply
rem --------------------------------------------------------------
rem define variables
dim document as object
dim dispatcher as object
rem --------------------------------------------------------------
rem get access to the document
document = ThisComponent.CurrentController.Frame
dispatcher = createUnoService("com.sun.star.frame.DispatchHelper")

rem --------------------------------------------------------------
dim args1(5) as new com.sun.star.beans.PropertyValue
args1(0).Name = "Flags"
args1(0).Value = "A"
args1(1).Name = "FormulaCommand"
args1(1).Value = 3
args1(2).Name = "SkipEmptyCells"
args1(2).Value = false
args1(3).Name = "Transpose"
args1(3).Value = false
args1(4).Name = "AsLink"
args1(4).Value = false
args1(5).Name = "MoveMode"
args1(5).Value = 4

dispatcher.executeDispatch(document, ".uno:InsertContents", "", 0, args1())

end sub

Nota

O modelo de componentes usado no LibreOffice é o Universal Network Objects (UNO) e o gravador de macro usa o despachante (dispatcher) UNO para a maioria dos comandos. No entanto, há dois problemas associados nesta abordagem técnica. Uma é que os despachos não são totalmente documentados e podem estar sujeitos a alterações. Outra é que o gravador ignora alguns valores das caixas de diálogo que são abertas durante a gravação de uma macro – É possível, portanto, que você grave uma macro complicada que na verdade não executa tudo como esperado. Para obter mais informações, pesquise “gravação de macro – limitações” no índice da Ajuda.

Escrever suas próprias funções

Criar uma função com macro

Você pode escrever uma macro e depois chamá-la como chamaria uma função Calc. Siga as etapas abaixo para criar uma função de macro simples:

1. Use Arquivo > Novo > Planilha na barra de menu para criar uma planilha, salve-a com o nome CalcTestMacros.ods, e deixe-a aberta no Calc.

2. Use Ferramentas > Macros > Organizar Macros > Basic na barra de menus para abrir a caixa de diálogo Macros Basic (Figura 8). Observe que o layout da caixa de diálogo Macros Basic nesta circunstância é diferente da versão que o Calc exibe quando o usuário clica no botão Parar gravação na caixa de diálogo Gravar macro (ver Figura 5)

1. A área Macro de lista os contêineres de bibliotecas de macros disponíveis, incluindo aqueles relacionados a quaisquer documentos do LibreOffice que estão abertos no momento. Minhas macros contém macros que você escreve ou adiciona ao LibreOffice e estão disponíveis para mais de um documento. Macros do LibreOffice contém macros que foram incluídas na instalação do LibreOffice e não devem ser alteradas.

2. Clique no botão Organizador para abrir a caixa de diálogo Organizador de macros Basic (Figura 9)

Clique na aba Bibliotecas e, na área Local, selecione a entrada para o nome do documento atual. A área Biblioteca atualiza para mostrar a biblioteca vazia Standard biblioteca.

1. Clique em Novo para abrir a caixa de diálogo Nova Biblioteca para criar uma biblioteca para este documento (Figura 10)

1. Insira um nome descritivo para a biblioteca (como AuthorsCalcMacros) e clique em OK para criar a biblioteca. A área Biblioteca da caixa de diálogo Organizador de macros Basic é atualizada para incluir o nome da biblioteca recém-criada. O nome de uma biblioteca pode conter até 30 caracteres. Observe que, em alguns casos, a caixa de diálogo pode mostrar apenas uma parte do nome.

1. Selecione a entrada AuthorsCalcMacros na área Biblioteca clique em Editar para editar a biblioteca. O Calc cria automaticamente um módulo chamado Módulo 1 e uma macro chamada Main. O Calc exibe o Ambiente de Desenvolvimento Integrado (IDE) do LibreOffice Basic, mostrado na Figura 12.

A Figura 12 mostra a configuração padrão para o IDE do LibreOffice Basic. Isto inclui:

• Uma barra de menu.

• Duas barras de ferramentas (Macro e Padrão). A barra de ferramentas Macro fornece vários ícones para editar e testar programas.

• O Catálogo de Objetos, permitindo a seleção do contêiner de biblioteca, biblioteca, módulo e macro necessários.

• A janela do Editor, para editar o código do programa LibreOffice Basic. A coluna do lado esquerdo é usada para definir pontos de interrupção no código do programa.

• A janela de observação (localizada à esquerda, abaixo do Catálogo de objetos e da janela do editor) exibe o conteúdo das variáveis ou matrizes durante um processo passo a passo.

• A janela de chamadas (localizada à direita, abaixo do Catálogo de Objetos e da Janela do Editor) fornece informações sobre a pilha de chamadas de procedimentos e funções quando um programa é executado.

• Uma área de controle de abas.

• Uma barra de status.

O LibreOffice Basic IDE fornece recursos poderosos para o desenvolvimento e depuração de macros do LibreOffice Basic. Uma descrição mais completa desta instalação está além do escopo deste documento, mas mais informações podem ser encontradas na Ajuda.

1. Na janela do Editor, modifique o código para que seja igual ao mostrado na Listagem 2. A adição importante é a criação da função NumberFive, que retorna o valor 5.

Dica

A instrução Option Explicit força todas as variáveis a serem declaradas antes de serem usadas. E se Option Explicit é omitida, as variáveis são definidas automaticamente no seu primeiro uso como tipo Variant.

Listagem 2. Função que retorna o valor 5

REM ***** BASIC *****
Option Explicit

Sub Main

End Sub

Function NumberFive ()

NumberFive = 5

End Function

1. No IDE do LibreOffice Basic, selecione Arquivo > Salvar na barra de menu ou clique no ícone Salvar na barra de ferramentas padrão, ou tecle Ctrl + C, para salvar o Módulo1 modificado.

Utilizar uma macro como função

Usando sua planilha recém-criada CalcTestMacros.ods, selecione uma célula e insira a fórmula =NumberFive() (Figura 13). O Calc encontra a macro, a chama e exibe o resultado (5) naquela célula.

Dica

Os nomes das funções não diferenciam maiúsculas de minúsculas. Na Figura 13, o nome da função foi inserido como NumberFive() mas Calc exibe como NUMBERFIVE() na barra de fórmulas.

Avisos de segurança de macro

Agora você deve salvar o documento Calc, fechá-lo e abri-lo novamente. Dependendo de suas configurações na caixa de diálogo Segurança de macro, acessada usando Ferramentas > Opções > LibreOffice > Segurança > Segurança de macro na barra de menu, o Calc pode exibir um dos avisos mostrados nas figuras 14 e 15.

No caso do aviso mostrado na Figura 14, você precisará clicar Ativar macros ou o Calc não permitirá que nenhuma macro seja executada no documento. Se você não espera que um documento contenha uma macro, é mais seguro clicar Desativar macros caso a macro seja um vírus.

No caso do aviso mostrado na Figura 15, o Calc não permitirá que nenhuma macro seja executada no documento e você deve clicar no botão OK para remover o aviso da tela.

Quando o documento é carregado com as macros desabilitadas, o Calc não será capaz de encontrar nenhuma função macro e indicará um erro em qualquer célula afetada exibindo o texto #NOME? nessa célula.

Bibliotecas carregadas / descarregadas

Ao abrir uma planilha, o Calc não abre todas as bibliotecas de macro que pode encontrar nos contêineres de biblioteca disponíveis, porque isso seria um desperdício de recursos. Em vez disso, o Calc carrega automaticamente apenas a biblioteca Standard dentro do contêiner de biblioteca Minhas Macros e a própria biblioteca Standard do documento. Nenhuma outra biblioteca é carregada automaticamente.

Quando reabrir sua planilha CalcTestMacros.ods, o Calc não contém uma função chamada NumberFive(). por isso verifica todas as bibliotecas de macro carregadas visíveis para a função. Bibliotecas carregadas em Macros do LibreOffice, Minhas Macros e o documento, são verificadas para uma função nomeada apropriadamente. Em nossa implementação inicial, a função NumberFive() é armazenada na biblioteca AuthorsCalcMacros, que não é carregada automaticamente quando o documento é aberto. Daí a função NumberFive() não é encontrada e uma condição de erro aparece na célula onde é chamada (Figura 16)

Utilize Ferramentas > Macros > Organizar Macros> Basic na barra de menus para abrir a caixa de diálogo Macros Basic (Figura 17). O ícone de uma biblioteca carregada (por exemplo, Standard) tem uma aparência diferente do ícone de uma biblioteca que não está carregada (por exemplo, AuthorsCalcMacros).

Clique no ícone de expansão ao lado de AuthorsCalcMacros para carregar a biblioteca. O ícone muda de aparência para indicar que a biblioteca agora está carregada. Clique em Fechar para fechar a caixa de diálogo Macros Basic.

Infelizmente, a célula contendo =NumberFive() em nossa implementação inicial ainda está com erro. O Calc não recalcula as células com erro, a menos que você as edite ou altere de alguma forma. A solução usual é armazenar macros usadas como funções na biblioteca Standard. Se a macro for grande ou se houver muitas macros, um esboço com o nome desejado é armazenado na biblioteca Standard. A macro stub carrega a biblioteca que contém a implementação e, em seguida, chama a implementação. As etapas a seguir ilustram esse método.

1. Escolha Ferramentas > Macros > Organizar Macros > Basic na barra de menus para abrir a caixa de diálogo Macros Basic. Selecione a macro NumberFive e clique Editar para abrir a macro para edição (Figura 18)

1. O Calc exibe o IDE do LibreOffice Basic (Figura 12 acima), com o cursor de entrada na janela do Editor na linha Function NumberFive(). Mude o nome de NumberFive para NumberFive_Implementation para que o código da função corresponda à Listagem 3.

Listagem 3. Altere o nome de NumberFive para NumberFive_Implementation

Function NumberFive_Implementation ()
NumberFive_Implementation = 5
End Function

1. Clique no botão Selecionar Macro na barra de ferramentas Padrão do IDE do LibreOffice Basic para abrir a caixa de diálogo Macros Basic (Figura 18)

2. Selecione a biblioteca Standard no documento CalcTestMacros.ods e clique no Botão Novo para criar um módulo. Insira um nome significativo, como CalcFunctions e clique OK. O Calc cria automaticamente uma macro chamada Main e abre o módulo para edição.

3. Crie uma macro no módulo CalcFunctions da biblioteca Standard que carrega a biblioteca AuthorsCalcMacros se ainda não estiver carregada e, em seguida, chama a função de implementação. Veja a Listagem 4.

Listagem 4. Crie uma nova função NumberFive para chamar a função NumberFive_Implementation

Funtion NumberFive ()
If NOT BasicLibraries.isLibraryLoaded("AuthorsCalcMacros") Then
BasicLibraries.LoadLibrary("AuthorsCalcMacros")
End If
NumberFive = NumberFive_Implementation ()
End Function

1. Salve, feche e reabra o documento Calc. Desta vez, se as macros estiverem habilitadas, a função NumberFive() funciona conforme o esperado.

Passar argumentos para uma macro

Para ilustrar uma função que aceita argumentos, escreveremos uma macro que calcula a soma de seus argumentos que são positivos. Ela ignorará os argumentos que são menores que zero (consulte a Listagem 5).

Listagem 5. PositiveSum calcula a soma de seus argumentos positivos

Function PositiveSum(Optional x)
Dim TheSum As Double
Dim iRow As Integer
Dim iCol As Integer

TheSum = 0.0
If NOT IsMissing(x) Then
If NOT IsArray(x) Then
If x > 0 Then TheSum = x
Else
For iRow = LBound(x, 1) To UBound(x, 1)
For iCol = LBound(x, 2) To UBound(x, 2)
If x(iRow, iCol) > 0 Then TheSum = TheSum + x(iRow, iCol)
Next
Next
End If
End If
PositiveSum = TheSum
End Function

A macro na Listagem 5 demonstra algumas técnicas importantes:

• O argumento x é Optional. Quando um argumento não é Optional e a função é chamada sem ele, o Calc exibe uma mensagem de aviso sempre que a macro é chamada. Se o Calc chamar a função muitas vezes, o erro será exibido muitas vezes.

• A função IsMissing verifica se um argumento foi passado antes de ser usado.

• A função IsArray verifica se o argumento é um valor único ou uma matriz. Por exemplo, =PositiveSum(7) ou =PositiveSum(A4). No primeiro caso, o número 7 é passado como um argumento e, no segundo caso, o valor da célula A4 é passado para a função. Em ambos os casos, IsArray retorna o valor False.

• Se um intervalo for passado para a função, ele será passado como uma matriz bidimensional de valores; por exemplo, =PositiveSum(A2:B5). As funções LBound e UBound são usadas para determinar os limites da matriz passada. Embora o limite inferior seja um, é considerado mais seguro usar LBound caso isso mude no futuro.

Dica

A macro na Listagem 5 é cuidadosa e verifica se o argumento é uma matriz ou um argumento singular. A macro não verifica se cada valor é numérico. Você pode ser tão cuidadoso quanto quiser. Quanto mais coisas você verifica, mais robusta a macro é, mas mais lenta ela é executada.

Passar um argumento é tão fácil quanto passar dois: adicione outro argumento à definição da função (consulte a Listagem 6). Ao chamar uma função com dois argumentos, separe os argumentos com uma vírgula; por exemplo, =TestMax(3, -4).

Listagem 6. TestMax aceita dois argumentos e retorna o maior

Function TestMax(x, y)
If x >= y Then
TestMax = x
Else
TestMax = y
End If
End Function

Argumentos são passados como valores

Os argumentos passados para uma macro do Calc são sempre por valores. Não é possível saber quais células, se houver, são usadas. Por exemplo, =PositiveSum(A3) passa o valor da célula A3, e PositiveSum não tem como saber que a célula A3 foi usada. Se precisar saber quais células são referenciadas em vez dos valores nas células, passe o intervalo como uma string, analise a string e obtenha os valores nas células referenciadas.

Escrever macros que agem como funções integradas

Embora o Calc encontre e chame macros como funções normais, elas não se comportam realmente como funções internas. Por exemplo, as macros não aparecem nas listas de funções. É possível escrever funções que se comportam como funções regulares escrevendo um Add-In. No entanto, este é um tópico avançado para programadores experientes e está além do escopo deste guia. Algumas informações, junto com links para leituras mais detalhadas, estão disponíveis na Ajuda.

Excluir macros do LibreOffice Basic

Use as seguintes etapas para excluir uma macro indesejada:

1. Acesse Ferramentas > Macros > Organizar Macros > Basic na barra de menus para abrir a caixa de diálogo Macros Basic (veja a Figura 18 acima)

2. Selecione a macro a ser excluída e clique no botão Excluir.

3. O Calc exibe uma caixa de diálogo de confirmação. Clique em Sim para continuar.

4. Clique no botão Fechar para remover a caixa de diálogo Macros Basic da tela.

Utilize as seguintes etapas para excluir um módulo indesejado:

1. Acesse Ferramentas > Macros > Organizar Macros > Basic na barra de menus para abrir a caixa de diálogo Macros Basic (veja a Figura 18 acima)

2. Clique no botão Organizador para abrir a caixa de diálogo Organizador de macro Basic (Figura 19)

3. Certifique-se de que a aba Módulos foi selecionada.

1. Selecione o módulo a ser excluído na lista Módulo.

2. Clique no botão Excluir.

3. O Calc exibe uma caixa de diálogo de confirmação. Clique em Sim para continuar.

4. Clique no botão Fechar para remover a caixa de diálogo Organizador de macros Basic da tela.

5. Clique no Fechar para fechar a caixa de diálogo Macros Basic.

Acessar células diretamente em macros

Você pode acessar os objetos internos do LibreOffice diretamente para manipular um documento Calc. Por exemplo, a macro na Listagem 7 adiciona os valores na célula A2 de todas as planilhas do documento atual. ThisComponent é definido automaticamente para fazer referência ao documento atual quando a macro é iniciada. Um documento Calc contém planilhas e a macro as acessa por meio de uma chamada para ThisComponent.getSheets(). Use getCellByPosition(col, linha) para retornar uma célula em uma linha e coluna específicas.

Listagem 7. SumCellsAllSheets adiciona os valores na célula A2 de cada planilha

Function SumCellsAllSheets()
Dim TheSum As Double
Dim i As integer
Dim oSheets
Dim oSheet
Dim oCell

TheSum = 0
oSheets = ThisComponent.getSheets()
For i = 0 To oSheets.getCount() - 1
oSheet = oSheets.getByIndex(i)
oCell = oSheet.getCellByPosition(0, 1) ' GetCell A2
TheSum = TheSum + oCell.getValue()
Next
SumCellsAllSheets = TheSum
End Function

Dica

Um objeto de célula suporta os métodos getValue(), getString() e getFormula() para obter o valor numérico, o valor da string ou a fórmula usada em uma célula. Use as funções de conjunto correspondentes para definir os valores apropriados.

Use a instrução oSheet.getCellRangeByName("A2") para retornar um intervalo de células por nome. Se uma única célula for referenciada, um objeto de célula será retornado. Se um intervalo de células for fornecido, um intervalo inteiro de células será retornado (consulte a Listagem 8) Observe que um intervalo de células retorna dados como uma matriz de matrizes, o que é mais complicado do que tratá-lo como uma matriz com duas dimensões, como é feito na Listagem 5.

Listagem 8. SumCellsAllSheets adiciona os valores nas células A2: C5 de cada planilha

Function SumCellsAllSheets()
Dim TheSum As Double
Dim iRow As Integer, iCol As Integer, i As Integer
Dim oSheets, oSheet, oCells
Dim oRow(), oRows()

TheSum = 0
oSheets = ThisComponent.getSheets()
For i = 0 To oSheets.getCount() - 1
oSheet = oSheets.getByIndex(i)
oCells = oSheet.getCellRangeByName("A2:C5")

REM The getDataArray() method returns strings and numbers
REM but is not used in this function.

REM The getData() method returns only numbers and is applicable
REM to this function.

oRows() = oCells.getData()
For iRow = LBound(oRows()) To UBound(oRows())
oRow() = oRows(iRow)
For iCol = LBound(oRow()) To UBound(oRow())
TheSum = TheSum + oRow(iCol)
Next
Next
Next
SumCellsAllSheets = TheSum
End Function

Dica

Quando uma macro é chamada como uma função Calc, a macro não pode modificar nenhum valor na planilha da qual a macro foi chamada, exceto o valor da célula que contém a função.

Ordenação

Considere classificar os dados mostrados na Figura 20. Primeiro, classifique na coluna B decrescente e, em seguida, na coluna A crescente.

O exemplo na Listagem 9 demonstra como classificar nessas duas colunas. Execute a macro clicando no ícone Executar na barra de ferramentas Macro do IDE do LibreOffice Basic.

Listagem 9. SortRange classifica células A1: C5 da planilha 1

Sub SortRange
Dim oSheet ' Calc sheet containing data to sort.
Dim oCellRange ' Data range to sort.

REM An array of sort fields determines the columns that are
REM sorted. This is an array with two elements, 0 and 1.
REM To sort on only one column, use:
REM Dim oSortFields(0) As New com.sun.star.util.SortField
Dim oSortFields(1) As New com.sun.star.util.SortField

REM The sort descriptor is an array of properties.
REM The primary property contains the sort fields.
Dim oSortDesc(0) As New com.sun.star.beans.PropertyValue

REM Get the sheet named "Sheet1"
oSheet = ThisComponent.Sheets.getByName("Sheet1")

REM Get the cell range to sort
oCellRange = oSheet.getCellRangeByName("A1:C5")

REM Select the range to sort.
REM The only purpose would be to emphasize the sorted data.
'ThisComponent.getCurrentController.select(oCellRange)

REM The columns are numbered starting with 0, so
REM column A is 0, column B is 1, etc.
REM Sort column B (column 1) descending.
oSortFields(0).Field = 1
oSortFields(0).SortAscending = FALSE

REM If column B has two cells with the same value,
REM then use column A ascending to decide the order.
oSortFields(1).Field = 0
oSortFields(1).SortAscending = TRUE

REM Setup the sort descriptor.
oSortDesc(0).Name = "SortFields"
oSortDesc(0).Value = oSortFields()

REM Sort the range.
oCellRange.Sort(oSortDesc())
End Sub

Visão geral das macros BeanShell, JavaScript e Python

Muitos programadores podem não estar familiarizados com o LibreOffice Basic e, portanto, o Calc suporta macros escritas em três outras linguagens que podem ser mais familiares. Estes são BeanShell, JavaScript e Python.

A linguagem de script de macro principal para Calc é o LibreOffice Basic e a instalação padrão do LibreOffice fornece um ambiente de desenvolvimento integrado (IDE) poderoso junto com mais opções para esta linguagem.

As macros são organizadas da mesma maneira para todas as quatro linguagens de script. o contêiner Macros do LibreOffice contém todas as macros que são fornecidas na instalação do LibreOffice. O contêiner Minhas Macros recipiente de biblioteca contém suas macros que estão disponíveis para qualquer um de seus documentos do LibreOffice. Cada documento também pode conter macros que não estão disponíveis para nenhum outro documento.

Quando você usa o recurso de gravação de macro, o Calc cria a macro no LibreOffice Basic. Para usar as outras linguagens de script disponíveis, você deve escrever o código sozinho.

Quando selecionar a execução de uma macro usando Ferramentas > Macros > Executar macro na barra de menus, o Calc exibe a caixa de diálogo Seletor de macro. Esta caixa de diálogo permite a seleção e execução de qualquer macro disponível, codificada em qualquer um dos idiomas disponíveis (Figura 21)

Quando selecionar editar uma macro usando Ferramentas> Macros> Editar Macros na barra de menus, o Calc exibe o IDE do LibreOffice Basic. Esta caixa de diálogo permite a seleção e edição de qualquer macro do LibreOffice Basic disponível, mas não de macros em outros idiomas.

O modelo de componente usado no LibreOffice é conhecido como Universal Network Objects ou UNO. 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 de programação e fornece um meio de acesso às várias interfaces de que elas podem precisar para executar alguma ação num documento.

Macros BeanShell

BeanShell é uma linguagem de script semelhante ao Java, lançada pela primeira vez em 1999.

Ao selecionar Ferramentas > Macros > Organizar Macros > BeanShell na barra de menus, o Calc exibe a caixa de diálogo Macros BeanShell (Figura 22)

Clique no botão Editar na caixa de diálogo Macros BeanShell para acessar a janela de depuração BeanShell (Figura 23)

Listagem 10 é um exemplo de macro BeanShell que insere o texto “Hello World from BeanShell” na célula A1 da planilha Calc ativa.

Listagem 10. Macro BeanShell de exemplo

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;

Macros JavaScript

JavaScript é uma linguagem de script de alto nível lançada pela primeira vez em 1995.

Quando selecionar Ferramentas > Macros > Organizar Macros > JavaScript na barra de menus, o Calc exibe a caixa de diálogo Macros JavaScript (Figura 24)

Clique no botão Editar na caixa de diálogo Macros JavaScript Macros para acessar o Rhino JavaScript Debugger (Figura 25). Instruções detalhadas para usar esta ferramenta podem ser encontradas no site da Mozilla em https://developer.mozilla.org/en-US/docs/Mozilla/Projects/Rhino/Debugger.

A Listagem 11 é um exemplo de macro JavaScript que insere o texto “Hello World do JavaScript” na célula A1 da primeira folha de uma planilha do Calc.

Listagem 11. Macro JavaScript de exemplo

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");

Macros Python

O Python é uma linguagem de programação de alto nível e propósito geral que foi lançada pela primeira vez em 1991.

Quando selecionar Ferramentas > Macros > Organizar Macros > Python na barra de menus, o Calc exibe a caixa de diálogo Macros Python (Figura 26)

Os recursos para editar e depurar scripts Python não estão integrados na interface de usuário padrão do LibreOffice. No entanto, você pode editar scripts Python com seu editor de texto preferido ou um IDE externo. A extensão Alternative Python Script Organizer (APSO) facilita a edição de scripts Python, em particular quando embutidos em um documento. Usando APSO, você pode configurar seu editor de código-fonte preferido, iniciar o shell Python integrado e depurar scripts Python. Para obter mais informações, pesquise Python no sistema de Ajuda do LibreOffice e visite a seção Projetando e desenvolvendo aplicativos Python do wiki da The Document Foundation ( https://wiki.documentfoundation.org/Macros/Python_Design_Guide ) e as páginas de ajuda começando em ( https://help.libreoffice.org/latest/en-US/text/sbasic/python/main0000.html )

A Listagem 12 é um exemplo de macro Python que define a célula A1 da primeira planilha num documento do Calc para o texto “Hello World from Python”.

Listagem 12. Macro Python de exemplo

import uno

def HelloWorld():

doc = XSCRIPTCONTEXT.getDocument()

cell = doc.Sheets[0]['A1']

cell.setString('Hello World from Python')

return

Trabalhar com macros VBA

Para o programador Excel / VBA, LibreOffice Basic é um Linguagem de programação básica muito semelhante ao VBA. O principal motivo pelo qual o VBA não funciona no Calc, embora o Calc seja capaz de ler a pasta de trabalho do Excel, é que o Calc usa um mecanismos para acessar a pasta de trabalho (chamado planilha no Calc) componentes, como células na planilha (chamado Folha no Calc). Especificamente, os objetos, atributos e métodos usam nomes diferentes e o comportamento correspondente às vezes é um pouco diferente.

Para converter um código VBA, você deve primeiro carregar o código VBA no LibreOffice.

Carregar o código VBA

Na página de Propriedades do VBA (Ferramentas > Opções > Carregar / Salvar > Propriedades do VBA ), você pode escolher se deseja manter as macros nos documentos do Microsoft Office abertos no LibreOffice (Figura 27).

Se escolher Carregar código Basic você pode editar as macros no LibreOffice. O código alterado é salvo em um documento ODF, mas não é retido se você salvar num formato do Microsoft Office.

Se escolher Salvar o código Basic original, as macros não funcionarão no LibreOffice, mas serão mantidas inalteradas se você salvar o arquivo no formato do Microsoft Office.

Se estiver importando um arquivo Microsoft Word ou Excel contendo código VBA, você pode selecionar a opção Código executável. Enquanto normalmente o código é preservado, mas tornado inativo (se você inspecioná-lo com o IDE Basic, notará que está todo comentado), com esta opção o código está pronto para ser executado.

Salvar o código Basic original tem precedência sobre Carregar código Basic. Se ambas as opções forem selecionadas e você editar o código desabilitado no LibreOffice, o código original do Microsoft Basic será salvo ao salvar em um formato do Microsoft Office.

Para remover qualquer possível vírus de macro do documento do Microsoft Office, desmarque Salvar o código Basic original. O documento será salvo sem o código Microsoft Basic.

Instrução Option VBA Support

A instrução Option VBA Support especifica que o LibreOffice Basic oferecerá suporte a algumas instruções, funções e objetos VBA. A instrução deve ser adicionada antes do código do programa executável em um módulo.

Nota

O suporte para VBA não é completo, mas cobre uma grande parte dos padrões de uso comuns.

Quando o suporte a VBA está habilitado, os argumentos de função do LibreOffice Basic e os valores de retorno são iguais aos de suas contrapartes de funções VBA. Quando o suporte é desabilitado, as funções do LibreOffice Basic podem aceitar argumentos e retornar valores diferentes de suas contrapartes do VBA.

Listagem 13. uso do Option VBA Support

Option VBASupport 1
Sub Example
Dim sVar As Single
sVar = Worksheets("Sheet1").Range("A1")
Print sVar
End Sub

Sem a instrução Option VBA Support, o código na Listagem 13 deve ser convertido para o LibreOffice Basic da Listagem 14.

Listagem 14. O código VBA convertido

Sub Example
Dim sVar As Single
Dim oSheet as Object
Dim oCell as Object
REM Worksheets(“Sheet1”).
oSheet = ThisComponent.getSheets().getByIndex(0)
REM Range("A1")
oCell = oSheet.getCellByPosition(0, 0)
sVar = oCell.getValue()
Print sVar
End Sub

A instrução Option VBASupport pode afetar ou auxiliar nas seguintes situações:

• Permitir caracteres especiais como identificadores. Todos os caracteres definidos como letras no conjunto de caracteres Latin-1 (ISO 8859-1) são aceitos como parte dos identificadores. Por exemplo, variáveis com caracteres acentuados em seus nomes.

• Criar constantes VBA incluindo caracteres não imprimíveis (vbCrLf, vbNewLine,...).

• Apoio, suporte as palavras chaves Private / Public para procedimentos.

• Instruções Set obrigatória para objetos.

• Valores padrão para parâmetros opcionais em procedimentos.

• Argumentos nomeados quando existem vários parâmetros opcionais.

• Pré-carregamento das bibliotecas do LibreOffice Basic.

VBA UserForms (Diálogos do LibreOffice Basic)

UserForms (Dialogs) aparecem frequentemente em macros que exigem sua interação e seleção de parâmetros. O trecho de código abaixo é uma receita para essas conversões, que não são tratadas automaticamente pelas opções do VBA.

Listagem 15. Exibição VBA de um UserForm [Dialog] chamado “MyForm”

Sub MyProc
MyForm.Show
End Sub

Listagem 16. Exibição do LibreOffice Basic de um UserForm [Dialog] chamado “MyForm”

Rem oDlg should be visible at the module level
Dim oDlg As Object
Sub MyProc
DialogLibraries.LoadLibrary("Standard")
oDlg = CreateUnoDialog(DialogLibraries.Standard.MyForm)
oDlg.execute()
End Sub

Nota

A variável oDlg é visível no nível do módulo para todos os outros procedimentos que estão acessando os controles na caixa de diálogo. Isso significa que todos os procedimentos de manipulação ou acesso aos controles neste painel de diálogo estão alojados em um único módulo.

Conclusão

Este capítulo fornece uma visão geral de como criar bibliotecas e módulos, usando o gravador de macro, usando macros como funções do Calc, escrevendo suas próprias macros sem o gravador de macro e convertendo macros VBA em macros do LibreOffice. Cada tópico merece pelo menos um capítulo, e escrever suas próprias macros para o Calc poderia facilmente preencher um livro inteiro. Em outras palavras, isso é apenas o começo do que você pode aprender.

Se já estiver familiarizado com a linguagem Basic (ou com uma linguagem de programação), o site do LibreOffice Extensions tem um conjunto de cartões de referência rápida do LibreOffice Basic no endereço https://extensions.libreoffice.org/?Tags%5B%5D=53&Tags%5B%5D=173.

Detalhes adicionais sobre os recursos macro do Calc podem ser obtidos no sistema de Ajuda ( https://help.libreoffice.org/latest/en-US/text/sbasic/shared/main0601.html?DbPAR=BASIC para obter informações gerais sobre macros ou, para encontrar algumas informações específicas de suporte VBA, vá para https://help.libreoffice.org/latest/en-US/text/sbasic/shared/03103350.html ), As páginas wiki da Document Foundation ( https://wiki.documentfoundation.org/Macros ) e outras fontes da Internet (por exemplo, o https://ask.libreoffice.org/ Site de perguntas e respostas).

Sumário

• Copyright

• Contribuidores

• Para esta edição

• Das edições anteriores

• Tradutores e revisores desta edição em português

• Comentários e sugestões

• Data de publicação e versão do software

• Nota para usuário Mac

• Introdução

• Sobre compatibilidade do Visual Basic for Application (VBA)

• Utilizar o gravador de macro

• Escrever suas próprias funções

• Criar uma função com macro

• Utilizar uma macro como função

• Avisos de segurança de macro

• Bibliotecas carregadas / descarregadas

• Passar argumentos para uma macro

• Argumentos são passados como valores

• Escrever macros que agem como funções integradas

• Excluir macros do LibreOffice Basic

• Acessar células diretamente em macros

• Ordenação

• Visão geral das macros BeanShell, JavaScript e Python

• Macros BeanShell

• Macros JavaScript

• Macros Python

• Trabalhar com macros VBA

• Carregar o código VBA

• Instrução Option VBA Support

• VBA UserForms (Diálogos do LibreOffice Basic)

• Conclusão