Guia Calc

Captulo 12
Macros do Calc
Automatizando tarefas repetitivas

Direitos autorais
Este documento protegido por Copyright 2010 por seus contribuidores listados abaixo. Podese distribuir e/ou modificar este trabalho, tanto sob os termos da Licena Pblica Geral GNU
(http://www.gnu.org/licenses/gpl.html), verso 3 ou posterior, ou da Licena de Atribuio Creative
Commons (http://creativecommons.org/licenses/by/3.0/), verso 3.0 ou posterior.
Todas as marcas comerciais dentro desse guia pertencem aos seus respectivos donos.

Contribuidores
Andrew Pitonyak
Barbara Duprey
Hal Parker

Simon Brydon
Alipio da Silva Resende
Fbio Farias

Raul Pacheco da Silva

Comentrios e contribuies
Por favor, direcione qualquer
documentation@libreoffice.org

comentrio

ou

sugesto

sobre

este

documento

para:

Crditos
Este captulo baseado no Captulo 1 do Guia do Calc 3.3 do OpenOffice.org. Os contribuidores
para este captulo so:
Andrew
Pitonyak Jean Hollis
Gary Schnabl
Claire Wood

Weber

Data de publicao e verso do software

Publicado em 29 de Abril de 2011. Baseado no LibreOffice 3.3.2.

Nota para usurios de Mac

Algumas combinaes de teclas e menus so diferentes no Mac, em comparao com os
utilizados no Windows e Linux. A tabela abaixo mostra algumas substituies mais comuns para
as instrues deste captulo. Para uma lista mais detalhada, acesse o menu Ajuda do aplicativo.
Windows/Linux

Equivalente no Mac

Resultado

Ferramentas Opes
menu de seleo

LibreOffice Preferncias

Acessa as opes de configurao

Clique com boto direito

Control+clique

Abre um menu de contexto

Ctrl (Control)

(Command)

Utilizada com outras teclas

F5

Shift++F5

Abre o Navegador

F11

+T

Abre a janela
Formatao

de

Estilos

Documentao do LibreOffice est disponvel em http://pt-br.libreoffice.org/suporte/documentao/

Contedo
Direitos autorais............................................................................................................................... 2
Nota para usurios de Mac.............................................................................................................. 2
Introduo........................................................................................................................................ 4
Utilizando o gravador de macro.......................................................................................................4
Escreva suas prprias funes........................................................................................................8
Usando uma macro como funo..............................................................................................10
Passando argumentos para uma macro....................................................................................13
Argumentos so passados como valor......................................................................................14
Escrevendo macros que agem como funes internas.............................................................14
Acessando as clulas diretamente.................................................................................................15
Classificando.................................................................................................................................. 16
Concluso...................................................................................................................................... 17

Macros do Calc

Introduo
Uma macro uma sequncia salva de comandos ou de teclas que foram armazenadas para uso
posterior. Um exemplo simples de uma macro uma que escreve seu endereo. A linguagem de
macro do LibreOffice muito flexvel, permitindo automatizao tanto de tarefas simples como
complexas. As macros so especialmente teis para repetir as tarefas seguindo o mesmo
caminho vrias vezes. Este captulo discute brevemente os problemas comuns relacionados a
programao de macros utilizando o Calc.

Utilizando o gravador de macro

O Captulo 13 do Guia do Iniciante, Introduo s Macros, oferece um entendimento bsico e
generalizado das capacidades das macros no LibreOffice com o uso do gravador de macros. Um
exemplo apresentado aqui sem as explicaes do Guia do Iniciante. Os passos a seguir criam
uma macro e executam a operao de colar especial com multiplicao.
1) Abra uma nova planilha
2) Digite os nmeros na planilha

Figura 1: Nmeros digitados

3) Selecione a clula A3, na qual contm o nmero 3, e copie o valor para a rea de
transferncia(Editar Copiar);
4) Selecione o range A1:C3;
5) Acesse o menu Ferramentas Macros Gravar macro para iniciar a gravao da
macro. Ser aberta a pequena caixa de dilogo Gravar macro com um nico boto Parar
gravao;

Figura 2: Boto de parar gravao

6) Use o menu Editar Colar especial para abrir o dilogo Colar Especial (Figura 3);
7) Marque a operao Multiplicar e clique OK. As clulas esto agora multiplicadas por 3
(Figura 4).
8) Clique em Parar gravao para que o gravador finalize a macro. A caixa de dilogo
Macros do LibreOffice Basic ser aberta (Figura 5).

Utilizando o gravador de macro

Figura 3: Caixa de dilogo Colar especial

Figura 4: Clulas multiplicadas por 3

9) Selecione o documento atual (ver Figura 5). Neste exemplo, o documento Calc atual o
Sem ttulo 1. Os documentos existentes mostram uma biblioteca chamada Standard. Esta
biblioteca no criada at que o documento seja salvo ou a biblioteca seja necessria,
ento neste momento seu novo documento no contm uma biblioteca. possvel criar
uma nova biblioteca para colocar a macro, mas isso no necessrio.

Utilizando o gravador de macro

1 Minhas Macros

5 Criar novo mdulo na biblioteca

2 Macros do LibreOffice

6 Macros na biblioteca selecionada

3 Documentos abertos

7 Documento atual

4 Criar nova biblioteca

8 Expandir/Ocultar lista

Figura 5: Componentes da janela Macros do LibreOffice Basic

10) Clique Novo mdulo, se no existia biblioteca, ento a biblioteca Standard
automaticamente criada e utilizada. Na caixa de dilogo Novo mdulo, digite um nome
para o novo mdulo ou deixe o nome como Module1, conforme sugerido;

11) Clique OK para criar o novo mdulo com o nome Module1. Selecione o recm-criado
mdulo criado Module1, digite ColarMultiplicando na caixa Nome localizado no canto
superior esquerdo, e clique Salvar. (Ver Figura 6.)

Utilizando o gravador de macro

Figura 6: Selecione o mdulo e digite o nome da macro

A macro que criada salvada no Module1 da biblioteca Standard no documento Sem ttulo 1. A
Listagem 1 mostra o contedo da macro.
Listagem 1: Colar especial com multiplicao
sub ColarMultiplicando
rem -------------------------------------------------------------rem define varivei
dim document
as object
dim dispatcher as object
rem -------------------------------------------------------------rem acesso ao documento
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,
args1())
end sub
Utilizando o gravador de macro

".uno:InsertContents",

"",

0,

Mais detalhes sobre a gravao de macros apresentado no captulo 13, Introduo s Macros,
do Guia do iniciante; ns recomendamos que voc leia isto se ainda no tiver feito isso. Mais
detalhes tambm sero fornecidos nas sees seguintes, porm no relacionado com a gravao
de macros.

Escreva suas prprias funes

O Calc pode chamar macros como funo Calc. Utilize os seguintes paos para criar uma simples
macro:
1) Crie um novo documento Calc com o nome CalcTestMacros.ods.
2) Utilize o menu Ferramentas Macros Organizar Macros LibreOffice Basic para
abrir a caixa de dilogo Macros do LibreOffice Basic. A caixa de listagem Macro de
apresenta todas as bibliotecas disponveis incluindo as contidas nos documentos abertos
no LibreOffice. Minhas macros contm as macros que voc escreveu ou adicionou no
LibreOffice. O item Macros do LibreOffice contm as macros includas no LibreOffice e no
devem ser alteradas.

Figura 7: Caixa de dilogo Macros do LibreOffice Basic

3) Clique Organizador para abrir a caixa de dilogo Organizador de macros do LibreOffice
Basic (Figura 8). Na guia Bibliotecas, selecione o documento que contm a macro.

Escreva suas prprias funes

Figura 8: Organizador de macros do LibreOffice Basic

4)

Clique Nova para abrir a caixa de dilogo Nova biblioteca.

Figura 9: Caixa de dilogo Nova biblioteca

5) Digite um nome significativo para a biblioteca (tal como: AuthorsCalcMacros) e clique Ok
para criar a biblioteca. O novo nome mostrado na lista de bibliotecas, mas na caixa de
dilogo somente ser visualizado parte do nome.

Figura 10: A biblioteca mostrada no organizador

6) Selecione AuthorsCalcMacros e clique Editar para entrar no modo de edio de biblioteca.
O Calc automaticamente cria um mdulo com o nome Module1 e uma macro com o nome
Main.

Escreva suas prprias funes

Figura 11: Ambiente de Desenvolvimento Integrado (IDE) do Basic

7) Modifique o cdigo para que o mesmo fique igual ao mostrado na Listagem 2. O mais
importante a ser includo a criao da funo NumberFive, a qual retorna o nmero 5.
O comando Option Explicit obriga que todas as varveis devem ser declaradas antes
de serem utilizadas. Se Option Explicit omitida, as variveis sero automaticamente
definidas no seu primeiro uso como do tipo Variant.
8) Salve o Module1 modificado.
Listagem 2: Funo que retorna o valor cinco
REM ***** BASIC
Option Explicit

*****

Sub Main
End Sub
Function NumberFive()
NumberFive = 5
End Function

Usando uma macro como funo

Usando o recm criado documento Calc CalcTestMacros.ods criado na seo anterior, entre com
a frmula =NumberFive() (veja a Figura 12). O Calc encontra a macro e executa.

Escreva suas prprias funes

10

Figura 12: Use a macro NumberFive() com uma funo do Calc

Dica

Nomes das funes no diferenciam letras maisculas e minsculas. Conforme a

Figura 12, mesmo que voc digite =NumberFive() o Calc mostra a frmula como
=NUMBERFIVE().

Salve o documento Calc, feche-o, e ento abra novamente. Dependendo de sua configurao em
Ferramentas Opes LibreOffice Segurana Segurana de macros, o Calc
mostrar o aviso da Figura 13 ou o aviso da Figura 14. Voc precisa clicar em Habilitar macros,
ou o Calc no permitir rodar nenhuma macro no documento. Se voc no espera que um
documento contenha macro, mais seguro que voc clique em Desabilitar macros caso a macro
seja um vrus.

Figura 13: Aviso de segurana do LibreOffice informando que este documento contm macros

Figura 14: Aviso se as macros esto desabilitadas

Escreva suas prprias funes

11

Se voc escolheu desabilitar as macros, ento quando o documento carregado o Calc no

conseguir encontrar a funo.

Figura 15: A funo ignorada

Quando um documento criado e salvo, ele automaticamente contm uma biblioteca chamada
Standard. Esta biblioteca carregada automaticamente quando o documento aberto. Nenhuma
outra biblioteca carregada.
O Calc no contm uma funo com o nome NumberFive(), ento ele verifica em todas bibliotecas
de macros abertas e visveis para a funo. As bibliotecas de Macros do LibreOffice, Minhas
Macros, e os documentos Calc so verificadas de forma a encontrar o nome apropriado (ver
Figura 7). A funo NumberFive() est armazenada na biblioteca AutoCalcMacros, que no est
quando o documento aberto.
Acesse o menu Ferramentas Macros Organizar macros LibreOffice Basic para abrir a
caixa de dilogo Macros do LibreOffice (veja Figura 16). Expanda CalcTestMacros e encontre a
biblioteca AuthorsCalcMacros. A cor do cone da biblioteca carregada diferente do cone da
biblioteca que no est carregada.
Clique o smbolo de expanso (normalmente um sinal de mais ou um tringulo) ao lado da
biblioteca AuthorsCalcMacros para carregar a biblioteca. O cone altera sua cor indicando que
agora a biblioteca est carregada. Clique Fechar para fechar a caixa de dilogo.
Infelizmente, a clula contendo =NumberFive() est com erro. O Calc no recalcula as clulas
com erro a menos que voc edite ou de alguma forma faa uma alterao. A soluo mais prtica
guardar as macros utilizadas como funo sempre na biblioteca Standard. Se a macro muito
grande ou se existem muitas macros, crie um prottipo da macro com o nome desejado na
biblioteca Standard. Este prottipo carrega a biblioteca contendo a implementao e ento chama
a implementao.
1) Utilize Ferramentas Macros Organizar macros LibreOffice Basic para abrir a
caixa de dilogo de Macros do LibreOffice Basic. Selecione a macro NumberFive e clique
Editar para abrir a macro para edio.

Figura 16: Selecione a macro e clique Editar

Escreva suas prprias funes

12

2) Troque o nome de NumberFive para NumberFive_Implementation (Listagem 3).

Listagem 3: Alterando o nome de NumberFive para Number Five_Implementation
Function NumberFive_Implementation()
NumberFive_Implementation() = 5
End Function
3) Na IDE Basic (veja Figura 11), passe o cursor do mouse sobre os botes da barra de
ferramentas para mostrar as dicas das ferramentas. Clique no boto Selecionar macro
para abrir a caixa de dilogo Macros do LibreOffice Basic (veja Figura 16).
4) Selecione a biblioteca Standard no documento CalcTestMacros e clique Novo para criar
um mdulo novo. Entre com um nome significativo como CalcFunctions e clique OK. O
LibreOffice automaticamente cria uma macro com o nome Main e abre o mdulo para
edio.
5) Crie uma macro na biblioteca Standard que faa a chamada da implementao da funo
(veja a Listagem 4). A nova macro carregar a biblioteca AuthorsCalcMacros, se ela ainda
no estiver carregada, e ento chama a implementao da funo.
6) Salve, feche e abra novamente o documento Calc. Desta vez, a funo NumberFive() est
funcionando.
Listagem 4: Alterando o nome da macro de NumberFive para NumberFive_Implementation.
Function NumberFive()
If NOT BasicLibraries.isLibraryLoaded("AuthorsCalcMacros") Then
BasicLibraries.LoadLibrary("AuthorsCalcMacros")
End If
NumberFive = NumberFive_Implementation()
End Function

Passando argumentos para uma macro

Para ilustrar uma funo que aceita argumentos, vamos escrever uma macro que calcula a soma
dos argumentos que so positivos isto ignorar os argumentos que forem menores que zero
(veja a Listagem 5).
Listagem 5: SomaPositivo calcula a soma dos argumentos positivos
Function SomaPositivo(Optional x)
Dim ASoma As Double
Dim iRow As Integer
Dim iCol As Integer
ASoma = 0.0
If NOT IsMissing(x) Then
If NOT IsArray(x) Then
If x > 0 Then ASoma = 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 ASoma = ASoma + x(iRow, iCol)
Next
Next
End If
End If
SomaPositivo = ASoma
Escreva suas prprias funes

13

End Function
A macro na Listagem 5 demonstra algumas tcnicas importantes:
1) O argumento x opcional. Quando um argumento no opcional e a funo chamada
sem ele, o LibreOffice mostra uma mensagem de aviso todas as vezes que a macro
chamada. Se o Calc chama a funo vrias vezes, ento a mensagem de erro ser
mostrada todas as vezes.
2) IsMissing verifica que um argumento foi passado antes do argumento ser utilizado.
3) IsArray verifica se o argumento passado na chamada da funo um valor simples ou
um conjunto de valores (array). Por exemplo =SomaPositivo(7) ou =SomaPositivo(A4).
No primeiro caso o nmero 7 passado como um argumento, no segundo caso, o valor da
clula A4 passado para a funo.
4) Se o intervalo for passado para a funo com um conjunto de dados bidimensional, por
exemplo, =SomaPositivo(A2:B5). Lbound e Ubound so utilizados para determinar os
limites inferior e superior do conjunto de dados (array) que est sendo utilizado. Embora o
limite inferior seja um, considerado mais seguro utilizar Lbound para o caso de ser
alterado no futuro.

Dica

A macro na Listagem 5 est considerando se o argumento um conjunto de dados ou

um valor nico, entretanto no verifica se cada valor um valor numrico. Conforme
sua necessidade, possvel ser mais cuidadoso nos itens a serem verificados.
Quanto mais itens forem verificados mais robusta a macro ficar, entretanto sua
execuo poder ficar mais lenta.

Passar um argumento to fcil quanto passar dois: acrescente outro argumento para a definio
da funo (ver Listagem 6). Quando for chamar uma funo com dois argumentos, separe os
argumentos com um ponto e vrgula; por exemplo, =TestMax(3; -4).
Listagem 6: TestMax aceita dois argumentos e retorna o maior deles.
Function TestMax(x, y)
If x >= y Then
TestMax = x
Else
TestMax = y
End If
End Function

Argumentos so passados como valor

Os argumentos passados para uma macro do Calc so sempre valores. Isto no possibilita saber
quais clulas, se houver, so utilizadas. Por exemplo, =SomaPositivo(A3) passa o valor da clula
A3, entretanto SomaPositivo no tem nenhum modo de saber o que a clula A3 contm. Se voc
quer saber quais as clulas so referenciadas em vez de seus valores, passe o intervalo como um
texto (string), analise a cadeia, ento pegue os valores nas clulas referenciadas.

Escrevendo macros que agem como funes internas

Embora o Calc encontra e utiliza macros como funes normais, elas no se comportam
realmente como funes internas (build-in). Por exemplo, as macros no aparecem nas listas de
funo. possvel escrever funes que se comportam como funes normais escrevendo um
suplemento (Add-In), entretanto este um tpico avanado que no coberto aqui.

Escreva suas prprias funes

14

Acessando as clulas diretamente

Pode-se acessar os objetos internos do LibreOffice diretamente para manipular um documento
Calc. Por exemplo, a macro da Listagem 7 soma os valores na clula A2 de todas as folhas do
documento atual. ThisComponent configurado pelo StarBasic quando a macro inicia a fazer a
referncia ao documento atual. ThisComponent.getSheets(). Utiliza getCellByPosition (coluna,
linha) para retornar uma clula na linha e coluna especfica.
Listagem 7: Soma as clulas A2 de todas folhas do documento.
Function SomaCelulaTodasPlanilhas()
Dim ASoma As Double
Dim i As integer
Dim oSheets
Dim oSheet
Dim oCell
oSheets = ThisComponent.getSheets()
For i = 0 To oSheets.getCount() - 1
oSheet = oSheets.getByIndex(i)
oCell = oSheet.getCellByPosition(0, 1) ' apanha a clula A2
ASoma = ASoma + oCell.getValue()
Next
SomaCelulaTodasPlanilhas = ASoma
End Function

Dica

Um objeto clula possui os mtodos getValue(), getString(), e

getFormula() como o objetivo de pegar o valor numrico, o texto, ou a frmula
utilizada em uma clula. Utilize as funes de conjunto apropriada conforme o
contedo da clula.

Utilize oSheet.getCellRangeByName("A2") para obter um intervalo de clulas por nome. Se

uma clula nica referenciada, ento um objeto da clula retornado. Se um intervalo de clula
passado, ento todo o intervalo de clulas retornado (ver Listagem 8). Note que um intervalo
de clulas retorna dados como um conjunto de um conjunto de dados (array de array), o qual
bem mais complicado de trabalhar que os dados em duas dimenses como feito na Listagem 5.
Listagem 8: Soma clulas A2:C5 de todas as folhas
Function SomaCelulaTodasPlanilhas()
Dim ASoma As Double
Dim iRow As Integer, iCol As Integer, i As Integer
Dim oSheets, oSheet, oCells
Dim oRow(), oRows()
oSheets = ThisComponent.getSheets()
For i = 0 To oSheets.getCount() - 1
oSheet = oSheets.getByIndex(i)
oCells = oSheet.getCellRangeByName("A2:C5")
REM getDataArray() retorna os dado como tipo variant
REM ento string so retornadas tambm.
REM getData() Retorna dados como tipo Double, ento somente
REM nmeros so retornados.
oRows() = oCells.getData()
For iRow = LBound(oRows()) To UBound(oRows())
Acessando as clulas diretamente

15

oRow() = oRows(iRow)
For iCol = LBound(oRow()) To UBound(oRow())
ASoma = ASoma + oRow(iCol)
Next
Next
Next
SomaCelulaTodasPlanilhas = ASoma
End Function
Quando uma macro chamada como uma funo, a macro no pode modificar
nenhum valor na planilha na qual a macro foi chamada.

Dica

Classificando
Considere a classificao dos dados da Figura 17. Primeiro, classifique a coluna B como
decrescente e depois a coluna A crescente

Figura 17: Classifica a coluna B decrescente e a coluna A crescente

O exemplo na Listagem 9 demonstra como pode ser feito o processo de ordenao em duas
colunas.
Listagem 9: Classifica as clulas A1:C5 na Planilha 1.
Sub ClassificaCelulas
Dim oSheet
' Folha Calc contendo dados para ordener.
Dim oCellRange
' rea a ser classificada.
REM
REM
REM
REM
Dim

Um conjunto de campos definem as colunas a serem

classificadas. Isto um array com dois elemento, 0 e 1.
Para classificar somente uma coluna, utilize:
Dim oSortFields(0) As New com.sun.star.util.SortField
oSortFields(1) As New com.sun.star.util.SortField

REM O descritor um array de propriedades.

REM A propriedade principal contm os campos a classificar.
Dim oSortDesc(0) As New com.sun.star.beans.PropertyValue
REM Selecione a folha com o nome "Planilha1"
oSheet = ThisComponent.Sheets.getByName("Planilha1")
REM Selecione as clulas a serem classificadas
oCellRange = oSheet.getCellRangeByName("A1:C5")

Classificando

16

REM Selecione a rea a ser classificada.

REM O nico propsito seria destacar a rea de classificao.
'ThisComponent.getCurrentController.select(oCellRange)
REM As colunas so numeradas iniciando em 0, ento
REM coluna A 0, coluna B 1, etc.
REM Classifique a column B (coluna 1) decrescente.
oSortFields(0).Field = 1
oSortFields(0).SortAscending = FALSE
REM Se a coluna B tem dua clulas com o mesmo valor,
REM ento utilize a coluna A como crescente para decidir a ordem.
oSortFields(1).Field = 0
oSortFields(1).SortAscending = True
REM Configure o descritor da classificao.
oSortDesc(0).Name = "SortFields"
oSortDesc(0).Value = oSortFields()
REM Classifique a regio que foi definida.
oCellRange.Sort(oSortDesc())
End Sub

Concluso
Este captulo fornece uma viso rpida de como criar bibliotecas e mdulos, utilizando o gravador
de macros, utilizando macros como funo do Calc, e escrevendo suas prprias macros sem o
uso do gravador de macros. Cada tpico merece pelo menos um captulo, e escrever suas
prprias macros para o Calc poderia facilmente encher um livro inteiro. Em outras palavras, o que
foi apresentado neste captulo apenas o comeo do que voc pode aprender!

Concluso

17