Introdução Ao OpenOffice.org Basic · rede, e se familiarizar com o Basic, antes de se aventurar no OOo Basic. É muito importante dominar os fundamentos de uma linguagem de programação

IntroduçãoIntroduçãoAoAo

OpenOffice.org Basic OpenOffice.org Basic

por

Noelson Alves Duarte

Copyright – Noelson Alves Duarte

É permitida a cópia, distribuição e / ou modificação deste documento, sob os termos da GNU Free Documentation License, Version 1.1 ou uma versão posterior publicada pela Free Software Foundation. Uma cópia da licença acompanha este documento.

Versão 2

Índice

1 Macros OpenOffice.org Basic........................................................................................................... 51.1 Introdução.................................................................................................................................. 51.2 Criando a Primeira Macro..........................................................................................................51.3 Executando a Primeira Macro....................................................................................................71.4 Compartilhando uma Macro...................................................................................................... 8

2 Diálogos Personalizados..................................................................................................................112.1 Introdução................................................................................................................................ 112.2 Criando um Diálogo ................................................................................................................112.3 Manipulando Eventos do Diálogo........................................................................................... 14

3 Pilotos Automáticos.........................................................................................................................173.1 Introdução................................................................................................................................ 173.2 Criando um Piloto Automático................................................................................................ 173.3 Manipulando Eventos do Piloto Automático...........................................................................19

4 Introdução a API do OpenOffice.org...............................................................................................214.1 Visão geral............................................................................................................................... 214.2 Objetos..................................................................................................................................... 224.3 Definindo objetos.....................................................................................................................244.4 Criando um novo documento...................................................................................................26

5 Trabalhando com Documentos........................................................................................................285.1 Carregando Documentos..........................................................................................................285.2 Salvando Documentos............................................................................................................. 305.3 Imprimindo Documentos......................................................................................................... 315.4 Fechando Documentos.............................................................................................................335.5 Identificando os Documentos Abertos.....................................................................................34

6 Documentos do Writer.....................................................................................................................366.1 Introdução................................................................................................................................ 366.2 Editando texto.......................................................................................................................... 366.3 Movendo-se pelo texto.............................................................................................................376.4 Formatando texto..................................................................................................................... 416.5 Formatando com estilo ............................................................................................................436.6 Obtendo o objeto selecionado..................................................................................................476.7 Localizando objetos................................................................................................................. 486.8 Busca e Substituição................................................................................................................ 506.9 Inserindo objetos......................................................................................................................526.10 Tabelas................................................................................................................................... 536.11 Desenhos................................................................................................................................59

7 Documentos do Calc........................................................................................................................637.1 Introdução................................................................................................................................ 637.2 Planilhas...................................................................................................................................637.3 Editando................................................................................................................................... 657.4 Navegando pelas Células......................................................................................................... 677.5 Obtendo objetos selecionados..................................................................................................697.6 Formatando.............................................................................................................................. 70

Formatando Parágrafos e Caracteres........................................................................................70 Mesclando Células................................................................................................................... 72 Inserindo Bordas...................................................................................................................... 72

Introdução ao OpenOffice.org Basic 1

Versão 2

Formatação Numérica.............................................................................................................. 73 Formatação Condicional.......................................................................................................... 74

7.7 Busca e Substituição................................................................................................................ 757.8 Ordenando................................................................................................................................777.9 Filtrando dados........................................................................................................................ 787.10 Inserindo Subtotais................................................................................................................ 807.11 Gráficos..................................................................................................................................817.12 Seleção durante a execução da macro....................................................................................857.13 Movimentando dados.............................................................................................................887.14 Dados de fontes externas....................................................................................................... 89

Vínculos................................................................................................................................... 89 Importando dados de um banco de dados................................................................................ 91

8 Banco de Dados............................................................................................................................... 938.1 Introdução................................................................................................................................ 938.2 Fontes de Dados.......................................................................................................................938.3 Conexões..................................................................................................................................978.4 Estrutura do Banco de Dados...................................................................................................99

Tabelas..................................................................................................................................... 99 Chave Primária.......................................................................................................................104 Índices.................................................................................................................................... 105 Segurança............................................................................................................................... 107

8.5 Registros................................................................................................................................ 108 Criando um RowSet............................................................................................................... 108 Navegando pelos registros..................................................................................................... 110 Acessando os dados................................................................................................................111 Alterando os dados.................................................................................................................112 Obtendo Metadados do RowSet.............................................................................................114

8.6 Consultas................................................................................................................................1148.7 Comandos SQL......................................................................................................................1178.8 Comandos SQL Preparados................................................................................................... 1198.9 Consultas Preparadas............................................................................................................. 1218.10 Vínculos............................................................................................................................... 121

9 Apêndice – Linguagem Basic........................................................................................................ 1239.1 Primeiros Passos.................................................................................................................... 1239.2 Elementos do Basic................................................................................................................125

Palavras reservadas................................................................................................................ 125 Regras para nomes................................................................................................................. 125 Comentários........................................................................................................................... 126 Tipos de dados internos..........................................................................................................126 Declaração de variáveis..........................................................................................................127 Matrizes..................................................................................................................................127 Escopo das variáveis.............................................................................................................. 128 Constantes simbólicas............................................................................................................ 129 Expressões..............................................................................................................................129

9.3 Fluxo de controle da execução...............................................................................................132 Comando de decisão If ... Then..............................................................................................132 Comando de decisão Select Case...........................................................................................133 Comando de repetição While ... Wend.................................................................................. 134

2 Introdução ao OpenOffice.org Basic

Versão 2

Comando de repetição For ... Next........................................................................................ 135 Comando de repetição Do ... Loop ........................................................................................136

9.4 Organização do Programa......................................................................................................137 Comandos...............................................................................................................................137 Sub-rotinas............................................................................................................................. 137 Funções.................................................................................................................................. 138 Passagem de Parâmetros........................................................................................................ 139 Chamada de Procedimentos................................................................................................... 139 Modelo Geral de uma Macro................................................................................................. 140

10 Mais informações........................................................................................................................ 14210.1 Na rede................................................................................................................................. 14210.2 Com o autor......................................................................................................................... 14310.3 Histórico, alterações, ...........................................................................................................143

11 Créditos, Agradecimentos, Licença............................................................................................. 14411.1 Créditos................................................................................................................................14411.2 Agradecimentos .................................................................................................................. 14411.3 Licença.................................................................................................................................144


Versão 2

Apresentação

Este documento é o resultado do meu esforço para aprender o OpenOffice.org Basic.

Ele está focado, principalmente, nas extensões do OpenOffice.org ao Basic, isto é, na API do OpenOffice.org. Assim sendo, as características básicas da linguagem de programação Basic não serão abordadas.

Se você já programou ou conhece algum dos “sabores” Basic e deseja escrever macros para o OpenOffice.org este é um bom local para começar. Senão, recomendo procurar algum curso na rede, e se familiarizar com o Basic, antes de se aventurar no OOo Basic. É muito importante dominar os fundamentos de uma linguagem de programação.

Todos os exemplos de código fonte foram testados com o OpenOffice.org, versão 1.0.1, exceto os pequenos blocos de código fora das sub-rotinas.

Para utilizar este texto, o OpenOffice.org deve estar instalado em seu computador. Após o Capítulo 3, recomendo que você instale, também, o Manual de Referência da API do OpenOffice.org (consulte o capítulo Mais Informações). O Manual de Referência sofre atualizações periódicas e sua versão atualizada está disponível, também, para consultas “on-line”.

Espero ter tempo para continuar aprendendo e acrescentando informações úteis aos programadores que, como eu, não dominam a língua inglesa. Portanto, periodicamente, procure por novas versões deste documento.

Como resultado de uma aprendizagem, esta Introdução, seguramente, contém muitos erros e inconsistências, espero contar com a sua ajuda para corrigí-los.

Em 20 de junho de 2003

O Autor

Considerações sobre a versão 2 desta Introdução:

A inclusão de um capítulo sobre Banco de Dados, de um apêndice sobre a Linguagem Basic e de novas seções ao longo do texto, praticamente dobrando o número de páginas, me convenceu a liberar esta Introdução como uma nova versão.

O OpenOffice.org também evoluiu, e, na sua nova versão, traz um gravador de macros. Isto amplia as possibilidades de programação para os usuários comuns e, também, para todos aqueles que desejam aprender a programar.

Porém, acredito que a chave para a programação do OpenOffice.org, está no conhecimento da sua API. Este foi o caminho adotado desde a primeira versão e, dele, não pretendo me afastar.

Em 25 de agosto de 2003

O Autor


Versão 2 Macros OpenOffice.org Basic

1 Macros OpenOffice.org Basic

1.1 Introdução

Uma macro é um programa escrito na linguagem OpenOffice.org Basic com a finalidade de automatizar tarefas do OpenOffice.org.

A linguagem OpenOffice.org Basic mantém as principais características das versões atuais do BASIC, no que diz respeito à sintaxe, tipos de dados, operadores, comandos, funções internas e organização geral do programa. Além disto, o OpenOffice.org Basic permite o acesso a uma grande quantidade de objetos, com seus métodos e propriedades, específicos do OpenOffice.org.

O OpenOffice.org tem um IDE (Integrated Development Environment - Ambiente de Desenvolvimento Integrado) completo, incluíndo: edição de código fonte, verificação de erros, criação de diálogos e gerenciamento de bibliotecas.

1.2 Criando a Primeira Macro

A nossa macro será bem simples. O operador vai digitar uma frase numa caixa de entrada, em seguida esta frase será adicionada na posição corrente do cursor de texto de um documento ativo do Writer.

Para começar:

a) Execute o Writer, crie um novo ducumento e salve-o como Primeira_Macro.sxw.

b) Na barra de menu, selecione Ferramentas – Macro. O diálogo Macro será exibido.

Figura 1: Diálogo Macro


Macros OpenOffice.org Basic Versão 2

Observe a árvore Macro de, no centro do diálogo, temos duas entradas principais soffice e Primeira_Macro.sxw, elas são recipientes (containers) para bibliotecas. Um nível abaixo, nas duas entradas, temos a biblioteca Standard. Dentro de soffice - Standard temos o módulo Module1.

O recipiente soffice sempre será carregado com o OpenOffice.org, ele tem bibliotecas globais, usadas em todos os documentos do OpenOffice.org. Observe que alguns módulos de soffice estão desativados.

Cada documento aberto tem seu próprio container com uma biblioteca Standard. Na figura acima, o único documento aberto é Primeira_Macro.sxw.

A lista, à esquerda do diálogo, exibe os nomes dos procedimentos (Sub-rotinas e funções) do módulo selecionado. O campo Nome da macro exibe o nome do procedimento selecionado. Ao selecionar o nome de um procedimento, os botões Executar, Atribuir e Editar são ativados.

Vamos continuar com a criação da nossa primeira macro:

a) Selecione a biblioteca Standard de Primeira_Macro.sxw.

b) Clique sobre o botão Novo para criar um novo módulo.

c) Aparece a caixa de entrada Novo Modulo, sugerindo o nome Module1.

d) Clique no botão OK para criar o novo módulo. O IDE Basic é carregado.

Figura 2: IDE Basic



e) Observe, no editor Basic, a definição de uma sub-rotina Sub Main ... End Sub. Note também que a aba Module1 está ativa.

f) Digite (ou copie e cole) o código fonte abaixo entre as linhas Sub Main e End Sub.

Dim oDocumento as Object Dim oTexto as Object Dim oCursorVista as Object Dim oCursor as Object Dim sInserir as String

' solicita o texto sInserir = InputBox("Digite o texto:", "Inserir Texto", "") ' testa se algo foi digitado if sInserir = "" then exit sub endif ' obtém o modelo do documento oDocumento = ThisComponent ' obtém o serviço Text do documento oTexto = oDocumento.getText() ' obtém a posição do cursor na GUI e cria um cursor de texto oCursorVista = oDocumento.getCurrentController().getViewCursor() oCursor = oTexto.createTextCursorByRange(oCursorVista.getStart()) ' insere o texto na posição corrente do cursor oTexto.insertString(oCursor, sInserir, FALSE)

Pronto, terminamos a nossa primeira macro. Lembre-se que ela está embutida no documento Primeira_Macro.sxw.

1.3 Executando a Primeira Macro

Antes de continuarmos, vamos analisar a janela do IDE Basic. Temos, na parte inferior da janela, uma área Observador, à esquerda, e outra Chamadas, à direita. A primeira será usada para observar valores de variáveis e a segunda mostra as chamadas a procedimentos, tudo durante a execução da macro.

Vejamos, também, a finalidade de alguns ícones da janela do IDE Basic:

Executar – executa uma macro até encontrar um Ponto de Interrupção.

Ponto de interrupção – define um ponto de interrupção.

Passo a passo – executa uma macro, linha a linha.

Parar – termina a execução de uma macro. Será ativado quando a execução da macro iniciar.

Macros – permite selecionar uma macro para execução.

Salvar código fonte como – salva o módulo corrente como um arquivo Basic.

Inserir código fonte - insere o código fonte de um arquivo Basic.

É chegada a hora de testarmos a nossa macro:



a) No editor Basic, posicione o cursor de texto na linha sInserir = InputBox( ... ). Clique no ícone Ponto de interrupção. Surge uma marca vermelha à esquerda da linha.

b) No campo Observador, digite sInserir e tecle Enter, para inspecionar o valor da variável durante a execução da macro. Note que o ícone Remover observador, à direita do campo, é ativado.

c) Clique sobre o ícone Executar. A execução da macro é iniciada e, no Ponto de interrupção, ela pára – note a seta amarela, à direita.

d) Clicando no ícone Passo a passo, acompanhe a execução da macro. Quando a caixa de entrada for exibida, digite o seu nome e clique sobre o botão OK. Continue a execução até o final, quando o ícone Parar for desativado.

Alterne para a janela do documento PrimeiraMacro.sxw, e veja se o seu nome foi inserido na posição do cursor, como desejado.

Se ocorreu algum erro, revise o código fonte.

Caso uma macro seja utilizada com freqüência, podemos configurar o OpenOffice.org para executá-la de modo mais fácil. Na opção de menu Ferramentas – Configurar, temos entradas para Menus – Teclado - Barra de ferramentas e Eventos, onde é possível associar macros a opções de menus, a ícones na barra de ferramentas, a uma combinação de teclas e a um evento do OpenOffice.org.

Antes de encerrar esta seção, retorne à janela do IDE Basic, para simularmos um erro no código fonte:

a) Na penúltima linha de código – oTexto.InsertString(...) - altere o nome da variável oCursor para oCurso.

b) Execute a macro. Surge uma caixa com uma mensagem de erro e um botão OK. Note que a seta de acompanhamento da execução torna-se vermelha na linha onde ocorre o erro. Após clicar em OK a execução da macro é finalizada e a linha com o erro permanece selecionada.

Figura 3: Erro de execução

c) Corrija o nome da variável de oCurso para oCursor. Feche o IDE Basic.

Salve o documento Primeira_Macro.sxw.

No próximo passo, veremos como disponibilizar uma macro para todos os documentos do OpenOffice.org.



1.4 Compartilhando uma Macro

As macros de uma biblioteca do container soffice / Standard são carregadas juntamente com o OpenOffice.org. Aquelas de um container de um documento qualquer são carregadas juntamente com o mesmo. Portanto, estarão disponiveis para execução somente quando o documento estiver aberto.

Nesta seção, veremos como exportar uma macro de um documento para o aplicativo OpenOffice.org. Aqui, mostraremos apenas os passos necessários para efetuar a tarefa.

Para disponibilizar uma macro de um documento para outros documentos do OpenOffice.org, siga os passos abaixo:

a) Selecione Ferramentas – Macro e clique sobre o botão Gerenciar.

b) Aparece o diálogo Gerenciar, clique sobre a aba Bibliotecas.

Figura 4: Diálogo Gerenciar

c) Selecione, na caixa de listagem Aplicação / Documento, a entrada soffice e pressione o botão Adicionar.

d) Um diálogo Abrir Arquivo será exibido. Localize e selecione o arquivo que contém a macro a ser compartilhada e clique sobre o botão Abrir.

e) O diálogo Inserir Bibliotecas será exibido. Note que as bibliotecas existentes no arquivo estão marcadas para compartilhamento. Desmarque aquelas que não serão compartilhadas e a biblioteca Standard, em seguida, clique sobre o botão Ok.



Figura 5: Inserir Bibliotecas

Após esta operação a biblioteca será acrescentada ao recipiente soffice. Normalmente, somente as macros da biblioteca Standard são carregadas com o OpenOffice.org. Para carregar uma outra biblioteca, escolha Ferramentas – Macro, selecione o recipiente e dê um duplo-clique sobre o nome da biblioteca.

Para as bibliotecas Standard, o método de exportar, não funciona adequadamente, pois o recipiente soffice possui a sua própria biblioteca Standard. Neste caso, devemos usar os recursos de edição do IDE Basic para compartilhar a macro.

Ative o IDE Basic e crie um novo módulo na biblioteca Standard do recipiente soffice. Em seguida, abra o documento com a macro e, no IDE Basic, ative o módulo que contém a macro a ser compartilhada, selecione toda a macro e copie, alterne para o novo módulo em soffice / Standard e cole a macro copiada, salve tudo e feche o OpenOffice.org. Agora a sua macro faz parte da biblioteca Standard de soffice e está disponível para execução no OpenOffice.org.

Se você pretende desenvolver macros para uso compartilhado, crie bibliotecas próprias para elas, principalmente se usarem diálogos. Para criar uma nova biblioteca, no diálogo Gerenciar (Figura 4), clique sobre o botão Novo, surge o diálogo Nova Biblioteca, na caixa de texto digite um nome para sua biblioteca e clique sobre o botão Ok.

O SDK do OpenOffice.org possui a ferramenta pkgchk para empacotamento de macros, o seu uso está fora do escopo desta Introdução. Consulte o Developers Guide para informações detalhadas.


Versão 2 Diálogos Personalizados

2 Diálogos Personalizados

2.1 Introdução

O OpenOffice.org Basic permite a criação de Diálogos Personalizados, através de um editor de Diálogos intuitivo e poderoso.

Diálogos são uma excelente solução para interação com o usuário, permitindo que o programador desenhe uma interface gráfica consistente para obter ou passar informações ao operador.

2.2 Criando um Diálogo

O Diálogo que vamos criar será bem simples. Na verdade, substituiremos a caixa de entrada usada em nossa primeira macro por um diálogo personalizado.

Antes de começarmos, precisamos recuperar o nosso arquivo Primeira_Macro.sxw:

a) Carregue o OpenOffice.org.

b) Abra o arquivo Primeira_Macro.sxw.

c) Escolha Ferramentas – Macro, selecione o Module1 da nossa macro e clique sobre o botão Editar para ativar o IDE Basic.

d) Clique com o botão direito do mouse sobre a aba Module1. No menu instatâneo, selecione Inserir – Diálogo. Aparece o editor de diálogos Basic, com um diálogo vazio. Note que foi criada uma página Dialog1.

e) Clique sobre o ícone Controles . Surge um quadro com vários ícones. Arraste este quadro pela barra de título (faixa superior) para fora da barra de ferramentas, posicionando-o do lado direito do diálogo.


Diálogos Personalizados Versão 2

Figura 6: Editor de Diálogos

Vejamos a finalidade de alguns ícones existentes no quadro de Controles.

Etiqueta – usado para colocar etiquetas no diálogo.

Botão – usado para colocar botões no diálogo.

Caixa de texto – permite inserir uma caixa de texto num diálogo.

Propriedades – exibe a janela de propriedades do controle selecionado. Será ativado quando algum controle for selecionado. Além da edição das propriedades, permite associar procedimentos (código) a eventos ocorridos no controle.

Ativar modo de teste – exibe o diálogo como se estivesse em execução.

Inserir Controles num Diálogo é uma operação em três passos:

1) ativar o ícone do controle no quadro de controles;

2) definir a área do diálogo onde o controle será posicionado. Para isto pressione o botão esquerdo do mouse e arraste formando um retângulo, em seguida, libere o botão do mouse;

3) definir as propriedades do controle.

Quando um controle é adicionado ao diálogo, o OpenOffice.org Basic automaticamente define um valor padrão para cada propriedade. Para exibir as propriedades de um controle selecionado, clique sobre o ícone Propriedades ou clique duas vezes sobre o controle. Note, também, que a janela Propriedades possui uma barra de rolagem para visualização.



Figura 7: Janela Propriedades

Vamos trabalhar em nosso diálogo:

a) Selecione o diálogo vazio, clicando na sua borda externa. Note que aparecem marcas em torno do mesmo. Podemos usar estas marcas para redimensionar o nosso diálogo.

b) Clique no ícone Propriedades para exibir a sua janela, como na figura acima. No campo Título – aba Geral – digite Inserir Frase e tecle Enter. Clique no botão Subir de Propriedades e observe o título do diálogo.

c) Adicione um controle Etiqueta ao diálogo. Para isto, clique no ícone Etiqueta, em seguida defina um retângulo na parte superior do diálogo. Defina a sua propriedade título para Digite o texto.

d) Coloque uma Caixa de Texto no diálogo, logo abaixo da etiqueta. Observe a sua propriedade Nome: TextField1. No código fonte, nos referimos a um controle pela sua propriedade Nome, daí a sua importância. Note, também, que este controle não tem a propriedade Título.

e) Vamos colocar dois botões, lado a lado, na parte inferior do diálogo, abaixo da caixa de texto. Defina os seus títulos para OK e Cancelar.

f) Ajuste o diálogo e seus controles de modo que fiquem com a aparência da figura abaixo.



Figura 8: Diálogo Inserir Frase

Bem, terminamos o nosso diálogo. Vamos verificar a sua aparência quando em execução. Clique sobre o ícone Ativar modo de teste no quadro de controles e, após observar o diálogo, clique em seu ícone Fechar para retornar ao editor.

Na próxima seção, daremos funcionalidade ao nosso Diálogo.

2.3 Manipulando Eventos do Diálogo

Vejamos como o diálogo que acabamos de projetar vai interagir com o operador: após a exibição do diálogo, o operador deve digitar o texto e depois pressionar o botão Ok ou pode, simplesmente, pressionar o botão Cancelar. Para cada uma destas ações (e muitas outras), o sistema emite mensagens de eventos.

Para dar funcionalidade ao diálogo, precisamos interceptar os eventos que nos interessam, isto é, o pressionamento do botão Ok ou Cancelar e, em seguida, fazer o processamento requerido.

O IDE Basic permite a associação de procedimentos a eventos de controles através da janela Propriedades e sua aba Eventos. A palavra procedimentos, acima, indica que precisamos de código fonte.

No IDE Basic, selecione o módulo Module1.

No editor de código Basic, digite (ou copie e cole) o código fonte abaixo, acima da Sub Main.

Private oDialogo as Variant

Sub dlgExecutaDialogo oDialogo = createUnoDialog(DialogLibraries.Standard.Dialog1) oDialogo.execute()End Sub

Sub dlgCancelaDialogo oDialogo.endExecute()End Sub

Sub dlgInserirFrase



Dim oDocumento as Object Dim oTexto as Object Dim oCursorVista as Object Dim oCursor as Object Dim sFrase as String

oDialogo.endExecute() ' note a referencia ao controle TextField1 do dialogo sFrase = oDialogo.Model.TextField1.Text

if sFrase = "" then exit sub endif ' obtém o modelo do documento oDocumento = ThisComponent ' obtém o serviço Text do documento oTexto = oDocumento.getText() ' obtém a posição do cursor na GUI e cria um cursor de texto oCursorVista = oDocumento.getCurrentController().getViewCursor() oCursor = oTexto.createTextCursorByRange(oCursorVista.getStart()) ' insere o texto na posição corrente do cursor oTexto.insertString(oCursor, sFrase, FALSE) End Sub

No código acima, declaramos a variável oDialogo (Private oDialogo as Variant) fora dos procedimentos, o que a torna visível em todo o módulo Module1.

Antes de exibir o diálogo, criamos um objeto oDialogo com createUnoDialog() e, para executá-lo, chamamos o seu método execute. Para fechar o diálogo chamamos o seu método endExecute (é chamado em dois procedimentos). Objetos UNO (criados com createUno) devem ser declarados com o tipo Variant e não Object.

A seguir, vamos associar os procedimentos aos eventos do diálogo.

Selecione a página Dialog1 para ativar o editor de diálogos.

Em nosso diálogo, selecione o botão OK e clique no ícone Propriedades. Surge a janela

Propriedades, clique na aba Eventos e, em seguida, clique no botão à direita do campo do evento Ao Iniciar. Surge a janela Atribuir macros com o evento Ao Iniciar selecionado. Na árvore Macros, expanda as entradas Primeira_Macro.sxw e Standard, clique sobre Module1. Surge a relação de procedimentos do módulo, selecione o procedimento dlgInserirFrase e clique sobre o botão Atribuir. Para fechar a janela, clique no botão OK.



Figura 9: Diálogo Atribuir macro

Agora, repita os passos acima para atribuir o procedimento dlgCancelaDialogo ao evento Ao Iniciar, do botão Cancelar do nosso diálogo.

Para o OpenOffice.org Basic, o primeiro procedimento no módulo é o ponto de entrada da macro. Logo, a Sub dlgExecutaDialogo será automaticamente executada toda vez que executarmos a nossa macro.

Teste a macro e o diálogo personalizado, clicando sobre o ícone Executar, na barra de ferramentas do IDE Basic. Digite uma frase qualquer na caixa de texto do diálogo e clique sobre o botão Ok. Após a execução da macro, verifique se a frase foi adicionada corretamente ao documento.

No próximo capítulo, vamos transformar o nosso diálogo simples num Piloto Automático.


Versão 2 Pilotos Automáticos

3 Pilotos Automáticos

3.1 Introdução

Um Piloto Automático é um Diálogo exibido em vários passos. É uma forma eficiente de guiar o usuário na execução de uma tarefa.

O OpenOffice.org traz, em sua instalação padrão, vários Pilotos Automáticos. Verifique o funcionamento de um deles, selecionando Arquivo – Piloto Automático – Carta.

3.2 Criando um Piloto Automático

Nesta seção, veremos como transformar o Diálogo Personalizado do capítulo anterior, num Piloto Automático.

A idéia geral é, num primeiro passo, obter a frase e, num segundo passo, solicitar uma posição para inserir a frase digitada. Para dar este efeito passo a passo, o OpenOffice.org permite a criação de diálogos com múltiplas páginas. O diálogo com a propriedade Página igual a 1 será exibido no primeiro passo, o da página 2 no segundo, e assim sucessivamente.

Os controles do OpenOffice.org Basic têm uma propriedade Página (Step), que controla em qual página de diálogo ele será exibido. Assim, os controles com a propriedade Página igual a 1 (um) serão visíveis no diálogo da página 1 (um), aqueles com a Página igual a 2 (dois) serão visíveis no diálogo da página 2 (dois) e assim por diante. Um controle será exibido em todos os passos quando a sua propriedade Página for igual a 0 (zero).

O último diálogo acessado no editor de diálogos, independente do número da sua página, será o primeiro a ser exibido na execução da macro. Portanto, após desenhar os diálogos do Piloto Automático, retorne para o diálogo da página 1 (um). Se você definir a página do diálogo para 0 (zero), todos os controles, de todas as páginas, serão exibidos.

Na transformação do diálogo em Piloto Automático, precisaremos de mais alguns controles e, também, alterar algumas propriedades dos controles existentes.

Carregue o Writer, abra o documento Primera_Macro.sxw, selecione Ferramentas – Macro, navegue até o modulo Primera_Macro - Standard – Module1 e pressione o botão Editar, para ativar o IDE Basic.

Clique sobre a aba Dialog1, ativando o Editor de Diálogos e redimensione o diálogo tornando-o mais largo. Selecione os botões Ok e Cancelar (clique em Ok, pressione a tecla Shift e clique em Cancelar), mova horizontalmente estes botões para a direita.

Na barra de ferramentas do IDE basic, clique no ícone Controles e posicione o quadro de controles ao lado do diálogo.

Clique no ícone Botão, no quadro de controles e adicione dois novos botões no diálogo, lado a lado e à esquerda do botão Ok.


Pilotos Automáticos Versão 2

Selecione o botão CommandButton3, clique no ícone Propriedades e defina a propriedade Titulo para << Voltar, altere o valor da propriedade Ativado de Sim para Não.

Selecione o botão CommandButton4 e defina a sua propriedade Titulo para Próximo >>.

Selecione o botão Ok e altere o seu Título para Concluir.

Selecione o diálogo (clique na sua borda externa) e defina a sua propriedade Página (Step) para 1 (um).

Selecione o controle Etiqueta e defina a sua propriedade Página para 1 (um).

Selecione o controle Caixa de Texto e defina a sua propriedade Página para 1 (um).

Agora, retoque a primeira página do Piloto Automático, tornando-a semelhante à figura abaixo.

Figura 10: Primeira Página do Diálogo do Piloto Automático

Bem, vamos prosseguir em nosso projeto, desenhando a Página 2 do Piloto Automático.

Selecione o diálogo e altere a propriedade Página para 2 (dois). Note que os controles Etiqueta e Caixa de Texto desaparecem, pois eles pertencem à Página 1. Os botões, que têm a página igual a 0 (zero), continuam visíveis.

Adicione uma Etiqueta na parte superior esquerda do diálogo e defina o seu Título para Selecione a posição. Observe que a propriedade página é igual a 2 (dois), o mesmo valor do diálogo.

Clique sobre o ícone Botão de Opção, no quadro de controles, e ponha três botões de opção, na parte superior direita do diálogo, um abaixo do outro.

Defina o Título do primeiro botão de opção para no Cursor e a sua propriedade Estado para Selecionado. Defina o Título do segundo botão de opção para no Início. Defina o Título do terceiro botão de opção para no Final.

Agora, ajuste os controles da segunda página do Piloto Automático, tornando-a semelhante à figura abaixo. Note que o botão de opção no Cursor é o padrão. A ativação e desativação dos botões Voltar e Próximo será feita em tempo de execução (pelo código fonte).


Versão 2 Pilotos Automáticos

Figura 11: Segunda Página do Diálogo do Piloto Automático.

Para finalizar o desenho do Piloto Automático, selecione o diálogo e retorne para a Página 1 (um), pois o OpenOffice.org, como padrão, exibe a última página acessada no Editor de Diálogos.

Na próxima seção, veremos o código fonte necessário para dar funcionalidade ao Piloto Automático.

3.3 Manipulando Eventos do Piloto Automático

O nosso Piloto Automático tem dois novos botões (Voltar e Próximo) e precisamos de código fonte para interceptar e processar os seus eventos.

Ative o IDE Basic e seu editor e digite (ou copie e cole) o código abaixo acima da Sub Main.

Sub dlgProximoDialogo oDialogo.Model.Step = 2 oDialogo.Model.CommandButton3.Enabled = true oDialogo.Model.CommandButton4.Enabled = falseEnd Sub

Sub dlgVoltarDialogo oDialogo.Model.Step = 1 oDialogo.Model.CommandButton3.Enabled = false oDialogo.Model.CommandButton4.Enabled = trueEnd Sub

Antes de inserir a frase, precisamos verificar a posição, selecionada no segundo passo (botões de opção) e tratar essa escolha adequadamente.

Digite o código abaixo na Sub dlgInserirFrase, após a linha oCursor = oTexto.CreateTextCursorByRange(...) e antes da linha oTexto.insertString(...).

' a posição da frase é no início ou no final if oDialogo.Model.OptionButton2.State = 1 then


Pilotos Automáticos Versão 2

oCursor.gotoStart(FALSE) elseif oDialogo.Model.OptionButton3.State = 1 then oCursor.gotoEnd(FALSE) endif

Agora, vamos ligar os procedimentos aos eventos que nos interessam.

Alterne para o editor de diálogos.

Selecione o botão Voltar e clique no ícone Propriedades. Surge a janela Propriedades, clique

na aba Eventos e, em seguida, clique no botão à direita do campo do evento Ao Iniciar. Surge a janela Atribuir macros com o evento Ao Iniciar selecionado. Na árvore Macros, expanda as entradas Primeira_Macro.sxw e Standard, clique sobre Module1. Surge a relação de procedimentos do módulo, selecione o procedimento dlgVoltarDialogo e clique sobre o botão Atribuir. Para fechar a janela, clique no botão OK.

Seguindo os passos acima, atribua o procedimento dlgProximoDialogo ao evento Ao Iniciar do botão Próximo.

Execute a macro e verifique se tudo ocorreu como o esperado.

Agora, você pode se aventurar escrevendo suas próprias macros. Como um ponto de partida, consulte o próximo capítulo em busca de informações complementares.


Versão 2 Introdução a API do OpenOffice.org

4 Introdução a API do OpenOffice.org

4.1 Visão geral

A API do OpenOffice.org está organizada por módulos. Um módulo contém um conjunto de elementos inter-relacionados. Dentre os módulos da API, podemos citar:

com.sun.star.awt - serviços relacionados a interface do usuáriocom.sun.star.beans - serviços para acesso a propriedadescom.sun.star.container - interfaces para coleções e recipientescom.sun.star.document - serviços para documentos do officecom.sun.star.drawing - serviços para desenhocom.sun.star.text - serviços para documentos textocom.sun.star.sdb - serviços para banco de dadoscom.sun.star.sheet - serviços para planilhascom.sun.star.util - serviços de utilidade diversaComo você pode notar, o módulo raiz é < com.sun.star > e todos os outros módulos estão subordinados a ele.

Normalmente, um módulo pode conter serviços, interfaces, estruturas, enumerações, definições de tipo e grupos de constantes. Por exemplo, entre os componentes encontrados no módulo beans, temos:

Services - relação de serviços do móduloInterfaces - relação de interfaces do móduloStructs - relação de est ruturas do móduloExceptions - relação de exceções do móduloEnums - relação de enumerações do móduloConstant Groups - relação de grupos de constantes do móduloUm módulo não precisa conter todos estes elementos.

Simplificando bastante, podemos dizer que:

Um serviço (Service), normalmente, representa um objeto.Uma interface (Interface) contém as definições dos métodos referentes a um dado objeto.Uma estrutura (Struct) é um tipo de dado contendo um ou mais campos.Uma exceção (Exception) é um indicador de erro passado ao sistema em tempo de execução.Uma enumeração (Enum) contém uma relação de constantes inteiras.Um grupo de constantes (Constant Group) define valores para determinadas constantes.

Serviços (Services), na API do OpenOffice.org, correspondem a objetos. Um serviço pode incluir outros serviços, oferecer interfaces e ter propriedades. No tópico sobre objetos, apresentaremos os serviços com mais detalhes.

As estruturas são tipos de dados contendo campos, do mesmo tipo ou não, agrupados sob um mesmo nome. Como exemplo, vamos estudar a estrutura < com.sun.star.awt.Size >, utilizada por diversos serviços da API. Ela define o tamanho de um objeto e contém dois campos:


Introdução a API do OpenOffice.org Versão 2

Struct < com.sun.star.awt.Size >Width - valor do tipo longo (Long), especificando a larguraHeight - valor do tipo longo (Long), especificando a altura

Uma estrutura pode incluir outras estruturas ou objetos como campos.

Podemos declarar uma variável simples ou um vetor do tipo estrutura, como abaixo:

Dim vTamanho As New com.sun.star.awt.Size ' declara uma variável simplesDim vetorTam (2) As New com.sun.star.awt.Size ' declara um vetor para 3 elementosDim vTam ( ) As New com.sun.star.awt.Size ' declara um vetor vazioO comando As New é utilizado em declarações de tipos de dados não suportado internamente pelo Basic. Note, ainda, a especificação completa do tipo de dado.

O acesso aos campos da estrutura se dá através do operador ponto ( . ) como em:

' define os valores dos campos da estrutura Size vTamanhovTamanho.Width = 2000vTamanho.Height = 1000' ou, aindanAltura = vTamanho.Height' acesso aos campos de um vetor de estruturavetorTam(0).Width = 5000vetorTam(0).Height = 2500

Uma enumeração contém uma relação de constantes com valores inteiros consecutivos. Por exemplo, a enumeração < com.sun.star.awt.PushButtonType > define tipos possíveis para um botão, são eles:

STANDARD - comporta-se como um botão padrãoOK - comporta-se como um botão OkCANCEL - comporta-se como um botão CancelarHELP - comporta-se como um botão AjudaNormalmente, os valores de uma enumeração são utilizados como propriedades de objetos, como abaixo:

oBotao1.PushButtonType = com.sun.star.awt.PushButtonType.STANDARD PushButtonType é uma propriedade do objeto botão. Devemos fornecer a especificação completa para o nome da constante.

Um grupo de constantes também contém valores para constantes relacionadas, contudo eles não são, necessariamente, consecutivos. A atribuição das constantes de um grupo a uma variável segue o mesmo padrão das enumerações.

4.2 Objetos

Já dissemos que um serviço é uma especificação de um objeto, que engloba um conjunto de interfaces e propriedades. Uma interface é uma coleção de métodos. Uma propriedade é um valor que determina uma característica de um serviço.

De uma maneira errônea, um objeto é como uma estrutura que, além dos campos comuns, pudesse conter campos especiais definindo procedimentos. Os campos comuns seriam as



propriedades e os especiais os métodos. Se você quiser descobrir o porquê da palavra errônea, procure algum texto introdutório sobre programação orientada a objetos.

Vamos analisar o serviço Spreadsheet, do módulo < com.sun.star.sheet >, que representa uma Planilha num documento do Calc, para fixar os conceitos.

< com.sun.star.sheet.Spreadsheet >:Inclui o serviço:

< com.sun.star.sheet.SheetCellRange >Exporta diversas interfaces, entre elas:

< com.sun.star.sheet.XSpreadsheet >< com.sun.star.container.XNamed >

Possui as propriedades:IsVisible - As BooleanPageStyle - As String

Uma interface é o local aonde os métodos dos objetos são definidos. No exemplo acima, a interface XSpreadsheet define métodos que criam um cursor para uma extensão de células, são eles:

createCursor - cria um cursor para toda a planilhacreateCursorByRange - cria um cursor para uma extensão de célulasUm método corresponde a um procedimento da linguagem Basic.

Existe outra característica das interfaces que deve ser citada. Uma interface pode ser derivada a partir de outra (superinterface). Neste caso, ela herda os métodos da superinterface. Como exemplo, vejamos a hierarquia da interface XSpreadsheet:

com.sun.star.uno.XInterface |___ com.sun.star.table.XCellRange |___ com.sun.star.sheet.XSheetCellRange |___ com.sun.star.sheet.XSpreadsheet

Note que XSpreadsheet é definida a partir da interface XSheetCellRange, que por sua vez é derivada de XCellRange. A conseqüência prática disto é: todos os objetos que oferecem XSpreadsheet suportam os métodos de XCellRange e XSheetCellRange.

Uma propriedade define uma característica de um objeto. Por exemplo, a propriedade IsVisible, acima, determina se a planilha a que se refere será ou não visível na interface gráfica.

Observe que Spreadsheet inclui o serviço SheetCellRange, isto significa que os métodos das suas interfaces e, também, as suas propriedades são suportadas por Spreadsheet.

Já vimos que o acesso aos campos de uma estrutura se dá através do operador ponto ( . ), isto também se aplica aos métodos e propriedades de um objeto. Então, supondo que temos uma variável oPlanilha1, do tipo objeto Spreadsheet, podemos escrever:

oCursor = oPlanilha1.createCursor ( ) ' cria um cursor abrangendo toda a planilhabVisivel = oPlanilha1.IsVisible ' atribui a bVisivel o valor da propriedade IsVisible



Devemos lembrar que um método pode ou não retornar um valor. No primeiro caso eles se assemelham às funções e, no segundo, às sub-rotinas do Basic.

Existem propriedades que são representadas por estruturas. Uma das mais utilizadas na API do OpenOffice.org é a estrutura < com.sun.star.beans.PropertyValue >, com quatro campos, entre os quais o par:

Name - cadeia com o nome da propriedade ( sensível a maiúsculas / minúsculas ).Value - tipo de dado Variant com o valor da propriedade.

O serviço MediaDescriptor, que contém muitas propriedades referentes a abertura e gravação de documentos, pode ser representado por um vetor da estrutura PropertyValue.

4.3 Definindo objetos

Para criar um serviço, usamos a função Basic createUnoService(), que retorna um objeto com suporte ao serviço ou Null, se não for possível a criação. Por exemplo, para obter o serviço Desktop usamos a chamada:

oDesktop = createUnoService( “com.sun.star.frame.Desktop” )

O parâmetro da função é a especificação completa para o serviço. Todos os serviços iniciam com com.sun.star, em seguida vem o nome do módulo, neste caso, frame e, por fim, o nome do serviço Desktop. Note, também, que a especificação é passada como uma cadeia.

Após a chamada, podemos verificar se o serviço foi criado com:

If isNull( oDesktop ) Then ' Erro na criação do serviço End If

Existem serviços que podem ser criados através de chamadas a métodos da API. Por exemplo, um documento do Writer pode conter objetos como texto e desenhos. Os serviços que representam estes objetos podem ser criados de duas maneiras:

Na primeira, usamos um método exclusivo para esta finalidade:

oObjetoTexto = oDocumento.getText ( )O método getText, retorna um objeto com o conteúdo texto de um documento do Writer.

Na segunda, podemos chamar um dos métodos do gerente de serviços:

oObjetoLinha = oDocumento.createInstance ( “com.sun.star.drawing.LineShape”)O método createInstance cria o objeto (serviço) especificado como parâmetro.

Um serviço (objeto) pode, também, ser parte das propriedades de um outro objeto. Neste caso, ele será obtido como o resultado de uma chamada ao método getPropertyValue ( ):

oPropriedade = oObjeto.getPropertyValue ( “Nome_da_Propriedade”)O método getPropertyValue retorna um objeto, se o valor da propriedade for um objeto.

Diversos serviços são dependentes de um contexto. Por exemplo, você não pode criar uma célula fora de uma planilha. Outros serviços não precisam de um ambiente para operar.



Existem, ainda, serviços que não oferecem nenhuma interface, servindo unicamente para obter e definir propriedades.

O Basic oferece duas propriedades que facilitam o acesso a serviços, são elas:

StarDesktop – é equivalente ao objeto retornado por uma chamada à função createUnoService( “com.sun.star.frame.Desktop” ). Digite o código abaixo numa nova sub-rotina, execute e observe o resultado:

MsgBox StarDesktop.Dbg_SupportedInterfaces ' ' é o mesmo que: ' Dim oDesktop oDesktop = CreateUnoService( "com.sun.star.frame.Desktop" ) MsgBox oDesktop.Dbg_SupportedInterfaces

ThisComponent – retorna o objeto documento que contém o código Basic, existe apenas em documentos do Writer, Calc, Impress ou Draw. Algumas de suas interfaces dependem do tipo de documento.

Dim oDocumento As Object oDocumento = ThisComponent

O OOo Basic tem três propriedades muito úteis para a inspeção de objetos, são elas:

Dbg_SupportedInterfacesretorna as interfaces suportadas pelo objeto

Dbg_Propertiesretorna as propriedades do objeto

Dbg_Methodsretorna os métodos suportados pelo objeto

Para obter estas propriedades, use a forma Objeto.Propriedade. Por exemplo, verifique as interfaces suportadas pelo modelo de documento, executando o código abaixo:

Sub Main MsgBox ThisComponent.Dbg_SupportedInterfacesEnd Sub

A interface com.sun.star.lang.XServiceInfo possui os métodos abaixo, úteis para inspeção de serviços:

getImplementationName ( ) As Stringretorna o nome de implementação do serviço

supportsService (sNome As String ) As Booleanretorna True se o serviço sNome for suportado

getSupportedServiceNames ( ) As String ()



retorna um conjunto de cadeias com os nomes dos serviços suportados, inclusive os indiretos

Vamos usar as facilidades de inspeção de objetos, oferecidas pelo OpenOffice.org Basic, para verificar o serviço Spreadsheet. Num documento do Calc, crie a macro abaixo e execute-a observando a saída:

Sub servicoSpreadsheet' exibe info do serviço Spreadsheet oDocumento = ThisComponent oSheet = oDocumento.Sheets(0) ' serviços suportados sServ = oSheet.getSupportedServiceNames() sMsg = "" For i = 0 To UBound(sServ()) sMsg = sMsg + sServ(i) + Chr$(10) Next i MsgBox sMsg ' interfaces suportadas MsgBox oSheet.Dbg_SupportedInterfaces ' métodos MsgBox oSheet.Dbg_Methods ' propriedades MsgBox oSheet.Dbg_PropertiesEnd Sub

Durante a execução, serão exibidos os serviços, interfaces, métodos e propriedades suportadas pelo objeto Spreadsheet.

Na próxima seção, vamos apresentar um exemplo, que utiliza diversos conceitos apresentados neste capítulo.

4.4 Criando um novo documento

Vamos, agora, desenvolver uma sub-rotina para criar um novo documento a partir de um modelo existente. O código fonte Basic, em linhas gerais, precisa tratar dos seguintes detalhes:

a) obter o caminho completo para o arquivo modelo;

b) carregar o arquivo, informando ao OpenOffice.org que se trata de um modelo;

A sub-rotina Sub criaNovoDocumento, abaixo, executa estas tarefas apropriadamente.

' --------------------------------------------' Cria um novo documento a partir de um modelo' --------------------------------------------Sub criaNovoDocumento Dim oDesktop As Variant Dim oDocumento As Object Dim mPropArquivo(0) As New com.sun.star.beans.PropertyValue Dim sUrl As String

' cria o objeto oDesktop oDesktop = createUnoService("com.sun.star.frame.Desktop")


http://com.sun.star.frame.Desktop/


' define a URL do arquivo modelo, ALTERE para seu sistema sUrl = "file:///D:/nad/openoffice/documentation.stw" ' define a propriedade AsTemplate para True mPropArquivo(0).Name = "AsTemplate" mPropArquivo(0).Value = True ' cria o objeto oDocumento oDocumento = oDesktop.loadComponentFromURL(sUrl,"_blank",0,mPropArquivo()) ' INSERIR CÓDIGO PARA SALVAR AQUI (esta macro será reutilizada adiante)End Sub

As linhas iniciadas pelo comando Dim declaram todas as variáveis usadas pela sub-rotina.

Para carregar um arquivo, usamos o método loadComponentFromURL(), que é definido por uma interface (XComponentLoader) do serviço Desktop. Então, precisamos de um objeto UNO Desktop, declarado na linha Dim oDesktop As Variant. Aqui, o tipo Variant segue uma recomendação do Developers Guide para a declaração de objetos UNO.

A variável sUrl (tipo String) recebe a especificação completa do caminho para o arquivo. Será passada como parâmetro do método loadComponentFromURL().

O método loadComponentFromURL() retorna um objeto Document. A linha Dim oDocumento As Object reserva memória para este objeto.

O método loadComponentFromURL(), recebe uma sequência de propriedades como parâmetro. A linha Dim mPropArquivo declara e define um vetor para esta sequência. A definição do objeto é feita com o operador New seguido do tipo de objeto (As New com.sun.star.beans.PropertyValue).

A linha oDesktop = createUnoService(...) se encarrega da criação do objeto Desktop.

A linha oDocumento = oDesktop.loadComponentFromURL(...) carrega o documento de acordo com os parâmetros e retorna um objeto do tipo Document. Note que a sequência mPropArquivo é passada como argumento seguida de (). O parâmetro “_blank” significa que um novo quadro será criado para o documento.

Pronto, agora digite (ou copie e cole) a Sub criaNovoDocumento, alterando a variável sUrl para conter um caminho completo do seu sistema, e execute a macro para ver seu resultado.

No próximo capítulo, aprenderemos mais sobre programação com documentos do OpenOffice.org.


Trabalhando com Documentos Versão 2

5 Trabalhando com Documentos

5.1 Carregando Documentos

Para carregar ou criar um documento do OpenOffice.org devemos:

a) Criar um objeto Desktop

Dim oDesktop As Variant oDesktop = createUnoService(“com.sun.star.frame.Desktop”)

b) Definir a URL

Você deve fornecer uma cadeia de caracteres com a especificação completa do caminho do documento, caso esteja abrindo um documento existente, na forma:

file:///caminho_completo_do_arquivoPara novos documentos, criados a partir do modelo padrão, existem URLs pré-definidas, que devem ser usadas de acordo com o tipo de documento:

URL Descriçãoprivate:factory/swriter Cria um novo documento do Writer

private:factory/scalc Cria um novo documento do Calc

private:factory/sdraw Cria um novo documento do Draw

private:factory/simpress Cria um novo documento do Impress

c) Definir as propriedades do descritor de mídia

O descritor de mídia é um serviço (com.sun.star.document.MediaDescriptor) que define como um recurso deve ser carregado. As propriedades do descritor são definidas numa sequência com.sun.star.beans.PropertyValue. Declare um vetor para a sequência, de acordo com o número de propriedades a alterar, como abaixo:

' declara um vetor vazio, para efeito de passagem como parâmetro Dim mPadrao() ' define um vetor para 1 propriedade (índice 0) Dim mPropArquivo(0) As New com.sun.star.beans.PropertyValue mPropArquivo(0).Name = "AsTemplate" mPropArquivo(0).Value = True ' define um vetor para 2 propriedades (índices 0 e 1) Dim mPropriedades(1) As New com.sun.star.beans.PropertyValue

Seguem as descrições de algumas propriedades (existem várias):


http://com.sun.star.beans.PropertyValue/

Versão 2 Trabalhando com Documentos

Propriedade Tipo DescriçãoAsTemplate Boolean Se True cria um novo documento, a partir do

documento carregado, mesmo que ele não seja um modelo. Se for um modelo e AsTemplate for False o documento será carregado para edição.

FilterName String Define um filtro a ser usado para carregar ou salvar o documento.

JumpMark String Após a carga, salta para uma posição (célula, bookmark, etc).

Hidden Boolean Se True, o documento não será exibido na interface gráfica

Overwrite Boolean Sobrescreve um documento ao salvar. Padrão é True.

ReadOnly Boolean Se o documento deve ser somente leitura ou leitura / gravação.

Unpacked Boolean Na gravação o documento não será compactado (zip).

Password String Senha para gravar ou carregar o documento.

d) Definir o quadro de destino

É o “frame” onde o documento será carregado / criado, se já existir um quadro com o nome especificado, ele será usado, senão um novo será criado.

Os nomes pré-definidos, a seguir, nunca devem ser usados como nome de quadros: “_blank”; “_default”; “_self”; “_parent”; “_top” e “_beamer”. Use “_blank” para criar um novo quadro.

e) Definir o flag de busca

É uma constante que define o tipo de algoritmo usado para encontrar o quadro de destino. Use um valor 0 para desconsiderar.

f) Chamar o método loadComponentFromURL()

Este método, do objeto Desktop, carrega o componente definido pela URL, dentro do quadro de destino. Vejamos seus detalhes:

loadComponentFromURL( URL As String, FrameDestino As String,FlagBusca As Long,Propriedades () As <com.sun.star.beans.PropertyValue> )

O valor de retorno é um objeto XComponent ou Null em caso de erro.

Eis um exemplo de chamada:

oDocumento = oDesktop.loadComponentFromURL(sUrl, "_blank", _ 0, mPropArquivo())

Isto é tudo, analise novamente o código da Sub criaNovoDocumento, do capítulo anterior.



5.2 Salvando Documentos

Para salvar um documento, devemos:

( as letras a), b) e c), abaixo, foram vistas no item 5.1 Carregando documentos)

a) Criar um objeto Document

Nomalmente, por uma chamada a loadComponentFromURL() ou ThisComponent.

b) Definir a URL

Trata-se do caminho completo do recurso.

c) Definir as propriedades

São as propriedades do descritor de mídia.

d) Chamar o método adequado

Os documentos do OpenOffice.org suportam os métodos abaixo para salvar componentes:

store ( )storeAsURL ( sURL As String, Propriedades As <com.sun.star.beans.PropertyValue> )storeToURL ( sURL As String, Propriedades As <com.sun.star.beans.PropertyValue> )

O método store ( ) simplesmente sobrescreve um arquivo e não deve ser usado num novo documento sem nome.

O método storeAsURL ( ) recebe dois parâmetros e funciona como o comando Salvar Como do OpenOffice.org.

O método storeToURL ( ) recebe dois parâmetros, salva o conteúdo do documento em sURL e não altera o arquivo original. Útil para exportar arquivos.

Exemplos de chamadas:

' salva um documento que já existe ThisComponent.store ( ) ' ou, supondo que oDocumento foi definido oDocumento.store ( )

Documentos abertos com loadComponentFromURL ( ), devem usar os métodos storeAsURL ou storeToURL.

Como exemplo, digite (ou copie e cole) o código fonte abaixo, após a linha

' INSERIR CÓDIGO PARA SALVAR AQUIda Sub criaNovoDocumento ( ), edite a variável sUrl conforme o seu sistema, execute a macro e verifique que um novo arquivo foi gravado em sURL..

' -------------------- ' Grava o novo arquivo ' -------------------- ' Define a URL do novo arquivo (ALTERE para seu sistema) sUrl = "file:///D:/nad/openoffice/novo_texto.sxw" ' define a propriedade Overwrite para False



mPropArquivo(0).Name = "Overwrite" mPropArquivo(0).Value = FALSE ' grava o novo documento oDocumento.storeAsURL(sUrl, mPropArquivo())

Temos, ainda, os métodos abaixo, relacionados com a tarefa de salvar arquivos:

isModified() As BooleanRetorna True se o recurso foi modificado, senão retorna False.

hasLocation ( ) As BooleanRetorna True se o arquivo já existe (foi gravado), senão retorna False.

GetLocation ( ) As StringRetorna uma String com a URL do recurso.

isReadonly ( ) As BooleanRetorna True se for somente leitura, em caso contrário retorna False

A seguir, temos um fragmento de código mais elaborado para salvar arquivos:

If (oDocumento.isModified) Then If (oDocumento.hasLocation And (Not oDocumento.isReadOnly)) Then oDocumento.store() Else oDocumento.storeAsURL(sURL, mPropArquivo()) End If End If

5.3 Imprimindo Documentos

O serviço OfficeDocument contém a interface XPrintable, que fornece os métodos para a impressão e definição de impressora no OpenOffice.org, são eles:

getPrinter ( ) As Variant < com::sun::star::beans::PropertyValue > setPrinter ( aImpressora As Variant < com::sun::star::beans::PropertyValue >)print ( xOpcoes As Variant < com::sun::star::beans::PropertyValue >)

Vamos analisar as características e chamadas de cada um destes métodos.

getPrinter () As Variant < com::sun::star::beans::PropertyValue > Este método retorna uma sequência com o descritor da impressora corrente. O descritor (PrinterDescriptor) contém a fila de impressão e as definições da impressora, conforme a tabela abaixo:

Propriedade DescriçãoName Uma cadeia (String) com o nome da fila de impressão

PaperOrientation Contém a orientação do papel



Propriedade DescriçãoPaperFormat Especifica um tamanho de papel padrão ou definido

pelo usuário

PaperSize Especifica o tamanho do papel em 1/100 mm

IsBusy True se a impressora estiver ocupada; False senão

CanSetPaperOrientation True se a impressora permite mudar a orientação do papel

CanSetPaperFormat True se a impressora permite mudar o formato do papel

CanSetPaperSize True se a impressora permite mudar o tamanho do papel

As quatro últimas propriedades são somente leitura.

Vejamos um exemplo que acessa as propriedades da impressora corrente:

Sub obtemDescritorImpressora Dim oDoc As Object Dim oDescImpr As Variant Dim sMsg As String oDoc = ThisComponent ' obtem o vetor de estruturas PrinterDescriptor oDescImpr = oDoc.getPrinter() ' obtem tamanho do vetor de estruturas iNrEstruturas% = UBound(oDescImpr) ' extrai os nomes das propriedades da impressora For n = 0 To iNrEstruturas% sMsg=sMsg + oDescImpr(n).Name + " " Next n ' exibe os nomes das propriedades MsgBox sMsg,0,"Propriedades Impressora" ' obtem e exibe o valor da propriedade PageFormat ' A3=0; A4=1; Letter/Carta=5; ... MsgBox oDescImpr(2).Value ' verifica se PageFormat pode ser alterada If oDescImpr(6).Value Then MsgBox "Formato da Página, pode ser alterado!" ' então altera para A4 oDescImpr(2).Value = 1 Else MsgBox "Formato da Página, não pode ser alterado!" End If ' exibe o valor de PageFormat novamente MsgBox oDescImpr(2).ValueEnd Sub

O código acima chama o método getPrinter ( ) para obter as propriedades da impressora corrente. Em seguida, no laço For ... Next, extrai os nomes de cada propriedade. E, mais abaixo, obtém e altera o formato da página, se possível.



setPrinter ( aImpressora As Variant < com::sun::star::beans::PropertyValue >)Atribui uma nova impressora ao documento. Pode implicar numa reformatação.

As propriedades da impressora são as mesmas da tabela acima.

print ( xOpcoes As Variant < com::sun::star::beans::PropertyValue >)Imprime o documento de acordo com as opções de impressão (PrintOptions) em xOpcoes. Estas opções são descritas na tabela a seguir:

Opção DescriçãoCopyCount ( Int ) Especifica o número de cópias a imprimir

FileName Cadeia com o nome de um arquivo para a impressão

Collate Se True todo o documento será impresso antes da próxima cópia, senão imprime todas as cópias página a página

Pages Uma cadeia com as páginas a serem impressas, por exemplo: “1;3;5-8;12”

Vejamos alguns exemplos de código fonte. Para imprimir um documento:

' imprimir o documento com as definições correntes Dim aOpcoes () oDocumento.print (aOpcoes() )

Para imprimir somente as páginas 1; 3; 5-8 e 12.

Dim aOpcoes(0) aOpcoes(0).Name = “Page” aOpcoes(0).Value = “1;3;5-8;12” ThisComponent.print ( aOpcoes() )

Para imprimir numa impressora que não a padrão, você precisa alterar a propriedade “Name” da impressora e chamar setPrinter definindo uma nova impressora, como abaixo:

Dim mImpressora(0) As New com.sun.star.beans.PropertyValue Dim aOpcoes() ' somente para passar o parâmetro ' mImpressora(0).Name="Name" mImpressora(0).value="Segunda_Impressora" ' define a nova impressora para o objeto, ' pode ocorrer uma formatação do documento oDocumento.setPrinter = mImpressora() ' imprime com as opcoes padrão oDocumento.print( aOpcoes() )


http://com.sun.star.beans.PropertyValue/


5.4 Fechando Documentos

Para fechar um documento, devemos considerar dois casos:

a) Aberto com loadComponentFromURL()

Vimos que este método retorna um objeto XComponent. A interface deste serviço fornece o método dispose(), que é usado para fechar um componente, sua chamada é simples:

oDocumento.dispose()

Acrescente a linha acima após a última linha da Sub criaNovoDocumento(), execute a macro e observe o resultado.

b) Aberto pela interface do OpenOffice.org

Se o documento foi carregado com o comando Arquivo – Abrir do OpenOffice.org e não houve a definição de um objeto Document, use a propriedade ThisComponent, como abaixo:

ThisComponent.dispose()

Cuidado, o método dispose() descarta todas as alterações efetuadas no documento. Portanto, antes de chamá-lo, certifique-se de gravá-las. Ou, ainda, use isModified() para alertar o usuário.

Existem maneiras mais seguras para controlar o fechamento de componentes, porém estão além do escopo desta Introdução.

5.5 Identificando os Documentos Abertos

Todos os documentos abertos são gerenciados pelo objeto Desktop. Cada documento é considerado um componente deste objeto, contudo nem todo componente é um documento. Por exemplo, se tivermos uma planilha e um documento de texto abertos, com o Navegador de Fonte de Dados ativo, existem três componentes no Desktop, dos quais dois são documentos.

A Sub exibeComponentes, abaixo, obtém uma enumeração dos componentes ativos, verifica quais são modelos de documentos e exibe informações sobre o seu tipo.

Sub exibeComponentes Dim oComponentes As Variant Dim oComp As Variant Dim sURL As String Dim sTipo As String

oComponentes = StarDesktop.getComponents().createEnumeration() n = 0 Do While (oComponentes.hasMoreElements()) oComp = oComponentes.nextElement()



' nem todos componentes são modelos com uma URL If HasUnoInterfaces(oComp, "com.sun.star.frame.XModel") Then sURL = oComp.getURL() If oComp.SupportsService("com.sun.star.sheet.SpreadsheetDocument") Then sTipo = "Calc" ElseIf oComp.SupportsService("com.sun.star.text.TextDocument") Then sTipo = "Writer" ElseIf oComp.SupportsService("com.sun.star.drawing.DrawingDocument") Then sTipo = "Draw" ElseIf oComp.SupportsService("com.sun.star.formula.FormulaProperties") Then sTipo = "Math" Else sTipo = "Outro" End If MsgBox sTipo + Chr$(13) + sURL End If n = n + 1 Loop MsgBox "Componentes: " + Str$(n)End Sub

Analise atentamente o código fonte acima, ele demonstra aspectos importantes da programação da API do OpenOffice.org. Note como se dá a criação de uma enumeração e como visitamos os seus elementos.

Após a identificação de um documento, você pode, por exemplo, comandar a sua impressão ou o seu fechamento, além, é claro, de poder manipular o seu conteúdo, aplicando as técnicas que serão vistas nos próximos capítulos.


Documentos do Writer Versão 2

6 Documentos do Writer

6.1 Introdução

Neste capítulo, veremos como efetuar tarefas simples de processamento de texto, como: edição, formatação, busca e substituição.

Vamos abordar o assunto através de exemplos práticos, com uma breve explicação dos aspectos mais importantes.

Um documento do Writer contém principalmente texto, organizado em parágrafos e tabelas. Além destes elementos básicos, ele suporta molduras, objetos embutidos, campos, gráficos, marcadores, índices e muitos outros objetos. Estes dados compreendem um modelo de documento.

Através do modelo, podemos manipular os dados independentemente da sua representação visual. Para lidar com o aspecto visual do documento, o modelo dispõe de um objeto controlador.

Alguns elementos de um documento (gráficos, molduras, etc) são nomeados e estão ancorados num parágrafo, caractere ou página. Os parágrafos não recebem um nome e nem um índice, de modo que seu acesso deve ser sequêncial.

6.2 Editando texto

Antes de começar a editar o texto de um documento, devemos ter em mente o seguinte:

a) Criar uma instância do componente a editar, isto é, um objeto que represente o documento do Writer;

b) Obter o conteúdo a editar, neste caso, um objeto com o texto do documento;

c) Fazer a edição do conteúdo, usando os métodos apropriados.

Crie um novo documento do Writer, vá para o IDE Basic, digite o código abaixo e execute a Sub editaTexto para ver o resultado.

Sub editaTexto Dim oDoc As Object Dim oTxt As Object Dim oTxtRange As Object Dim sStr As String oDoc = ThisComponent oTxt = oDoc.getText() sStr = "Esta é uma " oTxt.setString( sStr ) oTxtRange = oTxt.getEnd() sStr = "cadeia de caracteres "


Versão 2 Documentos do Writer

oTxtRange.setString( sStr )End Sub

Neste exemplo, usamos a interface XTextRange para editar texto. Eis os seus métodos:

getText() As Text retorna um objeto Text

getString() As Stringretorna a String contida no objeto

setString( sStr As String)define a String como o conteúdo do objeto

getStart() As Object <TextRange >retorna um objeto TextRange apontando para o início do objeto chamador

getEnd() As Object <TextRange>retorna um objeto TextRange apontando para o final do objeto chamador

Inicialmente, chamamos o método getText ( ), que retorna um objeto Text, este passo corresponde ao item b) acima.

Em seguida, na linha oTxt.setString(sStr), definimos uma cadeia de caracteres para o nosso objeto Text, isto significa que todo o conteúdo do documento – objeto oTxt - será substituído pela cadeia sStr de setString. Antes de inserir mais texto, precisamos obter o final do conteúdo de oTxt com a chamada ao método getEnd( ) e usar este novo objeto – TextRange – para inserir mais texto. Através do método getStart, poderíamos inserir texto no início.

Note, ainda, que as variáveis dos serviços Text e TextRange são declaradas como Object.

Atenção, oTxt também é um TextRange, assim podemos substituir a variável oTxtRange pelo encadeamento de métodos abaixo:

oTxt.getEnd ().setString ( sStr )

Este processo de edição é muito limitado. Podemos apenas substituir todo o conteúdo do texto e inserir texto no início ou no final do documento.

6.3 Movendo-se pelo texto

Para aumentar a flexibilidade na edição de texto, o modelo de documento nos oferece dois tipos de cursor: um cursor de texto e um cursor da vista. O primeiro opera sobre o conteúdo do documento independente da interface gráfica e o segundo representa o cursor visível na interface gráfica. Você pode criar quantos cursores desejar.

O alcance de um cursor tem um início e um final, que pode abranger uma faixa variável de texto ou coincidir num mesmo ponto. O alcance do cursor pode ser expandido durante o deslocamento do mesmo.

No Writer, além do cursor de texto, temos ainda: cursor de palavra, cursor de sentença e cursor de parágrafo, todos derivados do cursor de texto.



Vejamos, agora, as interfaces e métodos usados para flexibilizar a edição de texto.

A interface XSimpleText, derivada de XTextRange, é usada na criação do cursor de texto, na inserção de cadeias e de caracteres de controle, ela possui os seguintes métodos:

createTextCursor ( ) As Object <TextCursor>Retorna um objeto cursor de texto ( no início do conteúdo )

createTextCursorByRange (aPos As TextRange) As Object <TextCursor>Cria um objeto cursor de texto na posição especificada no parâmetro

insertString(aPos As TextRange, sStr As String, bFlag As Boolean)Insere a cadeia na posição. Se bFlag for True o conteúdo de aPos será substituído por sStr, senão sStr será acrescentada no final de aPos.

insertControlCharacter( aPos As TextRange, iChar As Integer, bFlag As Boolean )Insere um caractere de controle na posição aPos.

O serviço TextCursor, através da interface XTextCursor, provê métodos para o controle do estado e movimentação do cursor.

a) Métodos para mover o cursor:

goLeft (iNrChar As Integer, bExpande As Boolean) As Booleanmove o cursor para a esquerda iNrChar caracteres

goRight (iNrChar As Integer, bExpande As Boolean) As Boolean move o cursor para a direita iNrChar caracteres

gotoStart (bExpande As Boolean)move o cursor para o início do texto

gotoEnd (bExpande As Boolean)move o cursor para o final do texto

gotoRange (xRange As <TextRange>, bExpande As Boolean)move ou expande o cursor sobre o objeto TextRange

Em todos os métodos acima, se bExpande for True o alcance do cursor será expandido.

b) Métodos para controlar o estado do cursor:

collapseToStart ( )move a posição do final do cursor para o seu início

collapseToEnd ( )move a posição do início do cursor para o seu final

isCollapsed ( ) As Boolean retorna True se as posições inicial e final do cursor forem iguais

As interfaces XWordCursor, XSentenceCursor e XparagraphCursor, todas derivadas de XTextCursor, também fornecem métodos para controle e movimento do cursor.

a) Métodos de XWordCursor:

gotoNextWord (bExpande As Boolean) As Boolean gotoPreviousWord (bExpande As Boolean) As BooleangotoEndOfWord (bExpande As Boolean) As BooleangotoStartOfWord (bExpande As Boolean) As Boolean



isStartOfWord ( ) As BooleanisEndOfWord ( ) As Boolean

b) Métodos de XSentenceCursor:

gotoNextSentence (Expande As Boolean) As BooleangotoPreviousSentence (bExpande As Boolean) As BooleangotoStartOfSentence (bExpande As Boolean) As BooleangotoEndOfSentence (bExpande As Boolean) As BooleanisStartOfSentence ( ) As BooleanisEndOfSentence ( ) As Boolean

c) Métodos de XParagraphCursor:

gotoStartOfParagraph (bExpande As Boolean) As BooleangotoEndOfParagraph (bExpande As Boolean) As BooleangotoNextParagraph (bExpande As Boolean) As BooleangotoPreviousParagraph (bExpande As Boolean) As BooleanisStartOfParagraph ( ) As BooleanisEndOfParagraph ( ) As Boolean

Antes de apresentar um exemplo, vejamos os caracteres de controle que podem ser inseridos num documento do Writer. Na interface gráfica, eles são chamados de caracteres não imprimíveis e têm funções especiais na apresentação final do documento.

Para facilitar o seu emprego, estes caracteres estão definidos como constantes, no grupo de constantes com.sun.star.text.ControlCharacter. Eles podem ser inseridos no texto com o método insertControlCharacter () ou como parte do conteúdo de uma cadeia, neste caso, usando o seu código Unicode.

Eis uma relação dos caracteres de controle com os seus respectivos códigos:

PARAGRAPH_BREAK Insere uma quebra de parágrafo 0x000D

LINE_BREAK Quebra de linha dentro de um parágrafo 0x000A

HARD_HYPHEN Caractere que aparece como um travessão. Hifenização não remove.

0x2011

SOFT_HYPHEN Marca uma posição preferida para hifenização. 0x00AD

HARD_SPACE Espaço com tamanho fixo. 0x00A0

APPEND_PARAGRAPH

Acrescenta um novo parágrafo Não tem

Vamos encerrar esta seção com um exemplo demonstrando o emprego de alguns dos conceitos e métodos apresentados.

Ative o IDE Basic, digite (ou copie e cole) o código fonte a seguir e execute a sub-rotina Sub processaTexto. Ela insere texto, caracteres de controle e uma quebra de página num novo documento sem nome. Depois, seleciona e substitui duas palavras por uma cadeia vazia.

Sub processaTexto



Dim oDesktop As Variant Dim oDoc As Object Dim oCursor As Object Dim oTexto As Object Dim mPropArquivo() Dim sStr As String

oDesktop = createUnoService("com.sun.star.frame.Desktop") oDoc = oDesktop.loadComponentFromURL("private:factory/swriter",_ "_blank", 0, mPropArquivo()) oTexto = oDoc.getText() oCursor = oTexto.createTextCursor() sStr = "Este é o texto do primeiro parágrafo do documento" With oTexto ' insere o texto na posição corrente do cursor .insertString(oCursor, sStr, False) ' insere um parágrafo .insertControlCharacter(oCursor,_ com.sun.star.text.ControlCharacter.PARAGRAPH_BREAK, False) .insertString(oCursor, "Este é o segundo parágrafo ", False) .insertControlCharacter(oCursor, _ com.sun.star.text.ControlCharacter.PARAGRAPH_BREAK, False) End With ' insere uma nova página oCursor.gotoStartOfParagraph(True) oCursor.breakType = com.sun.star.style.BreakType.PAGE_BEFORE oTexto.insertString(oCursor, "Estou numa nova página.", False) ' move o cursor sem expansão oCursor.gotoStart(False) oCursor.gotoNextWord(False) oCursor.gotoNextWord(False) oCursor.gotoNextWord(False) ' move o cursor expandindo, i.é, seleciona “texto do” oCursor.gotoNextWord(True) oCursor.gotoNextWord(True) ' substitui o texto entre o início e o final do cursor oTexto.insertString(oCursor, "", True)

End Sub

No código acima, estude o emprego do parâmetro bExpande (True ou False) ele é muito importante.

Outro aspecto é a inserção da quebra de página. Não existe um caractere de controle para quebra de página ou coluna. Ela é uma propriedade do parágrafo. Note que usamos oCursor para definir uma propriedade do parágrafo (oCursor.breakType). Isto é possível porque o objeto TextCursor herda características de TextRange.

Os valores possíveis para a propriedade breakType (quebra de página e coluna) estão enumerados em com.sun.star.style.BreakType, aqui usamos PAGE_BEFORE.



Finalmente, observe, no novo documento, que o cursor da vista encontra-se no final do mesmo, apesar da última ação (seleção e substituição) ter ocorrido no primeiro parágrafo, o que demonstra a independência entre o cursor de texto e a interface gráfica.

Lembre-se, ainda, que o acesso à interface gráfica se dá através do controlador do modelo do documento. O código fonte da sub-rotina dlgInserirFrase, do Capítulo 3 (Piloto Automático), mostra como acessar o controlador e criar um cursor da vista.

6.4 Formatando texto

Esta é outra tarefa comum em processamento de textos. Temos duas abordagens para formatar um conteúdo de texto: a primeira é aplicar as características desejadas diretamente sobre o objeto, sobrescrevendo as definições básicas, por exemplo, selecionar um parágrafo e mudar o seu ajustamento; a segunda consiste em aplicar um estilo pré-definido de formatação, por exemplo selecionar um parágrafo e mudar o seu estilo de Padrão para Título.

Inicialmente, vamos demonstrar a primeira abordagem. Existe uma grande quantidade de propriedades relacionadas à formatação, como propriedades de caracteres e de parágrafos.

O serviço com.sun.star.style.CharacterProperties define as propriedades comuns de caracteres. Eis algumas delas:

Propriedade DescriçãoCharFontName Especifica o nome do estilo da fonte

CharFontStyleName

Contém o nome do estilo da fonte

CharFontFamily Contém a família da fonte conforme (com.sun.star.awt.FontFamily)

CharHeight Valor com a altura do caracteres em pontos

CharUnderline Contém o valor do caractere do sublinhado (com.sun.star.awt.Underline)

CharWeight Contém o valor do peso da fonte (com.sun.star.awt.FontWeight)

CharPosture Contém o valor da postura da fonte (com.sun.star.awt.FontSlant)

CharFlash Se True o caractere pisca. É opcional

CharStrikeout Define o tipo de risco do caractere (com.sun.star.awt.FontStrikeout)

CharRotation Define a rotação do caractere em graus

Na tabela acima, as referências ao módulo com.sun.star.awt, contém possíveis valores para as respectivas propriedades dos caracteres.

O serviço com.sun.star.style.ParagraphProperties define as propriedades dos parágrafos. A tabela abaixo apresenta algumas:



Propriedade DescriçãoParaAdjust Define o tipo de ajuste (com.sun.star.style.ParagraphAdjust)

ParaBackColor Contém a cor de fundo, é opcional

ParaLastLineAdjust

Define o ajuste da última linha

ParaLeftMargin Define a margem esquerda em 1/100 mm ( As Long )

ParaRightMargin Define a margem direita em 1/100 mm ( As Long )

ParaTopMargin Define a margem superior do parágrafo em 1/100 mm (As Long)

ParaBottomMargin

Define a margem inferior do parágrafo em 1/100 mm (As Long)

ParaStyleName Contém o nome do estilo de parágrafo corrente, é opcional.

LeftBorder Define a borda esquerda, é opcional (com.sun.star.table.BorderLine )

RightBorder Define a borda direita, é opcional (com.sun.star.table.BorderLine )

TopBorder Define a borda superior, é opcional (com.sun.star.table.BorderLine )

BottomBorder Define a borda inferior, é opcional (com.sun.star.table.BorderLine )

BorderDistance Valor com a distância da borda ao objeto (As Long)

ParaFirstLineIndent

Valor longo com a identação da primeira linha, é opcional

ParaVertAlignment

Define o alinhamento vertical (com.sun.star.text.ParagraphVertAlign)

Novamente, as referências com.sun.star contém valores possíveis para as respectivas propriedades, geralmente um valor de 0 a N para constantes. Veja a seguir algumas delas.

Constantes de com.sun.star.style.ParagraphAdjust: LEFT, RIGHT, BLOCK, CENTER e STRETCH.

Constantes de com.sun.star.text.ParagraphVertAlign: AUTOMATIC, BASELINE, TOP, CENTER e BOTTOM.

Existem muitas outras propriedades para caracteres e parágrafos, uma consulta ao Developers Guide e ao Reference Manual, ambos da Sun Microsystems Inc, é indispensável para aqueles que desejam programar para o OpenOffice.org.

Vamos retomar o nosso último exemplo a Sub processaTexto. Desejamos mudar a inclinação e cor da fonte da palavra “segundo” e, também, o estilo de um parágrafo de Padrão para Título. Digite o código abaixo, após a última linha da sub-rotina, execute-a e observe o resultado.



' ---------------------- ' código para formatação ' ---------------------- oCursor.gotoNextParagraph(FALSE) oCursor.gotoNextWord(False) oCursor.gotoNextWord(False) oCursor.gotoNextWord(False) oCursor.gotoNextWord(True) oCursor.CharPosture = com.sun.star.awt.FontSlant.REVERSE_ITALIC oCursor.CharColor = RGB(255,0,0) ' aplica estilo de parágrafo oCursor.gotoNextParagraph(FALSE) oCursor.paraStyleName = "Heading"

Note a atribuição da propriedade CharPosture a um valor enumerado REVERSE_ITALIC e, ainda, a alteração do estilo de parágrafo paraStyleName para “Heading”. Em se tratando de programação, os nomes permanecem em inglês, diferindo dos nomes apresentados pelo OpenOffice.org no Catálogo de Estilos.

6.5 Formatando com estilo

Vejamos, agora, a segunda abordagem para formatação, que é a aplicação de um estilo sobre o objeto. Sempre que possível, formate os seus documentos usando este método.Isto facilita futuras alterações, pois basta mudarmos as características de um estilo para que todos os objetos com ele formatados sejam alterados.

O módulo com.sun.star.style possui diversas interfaces para formatação, definição e acesso aos estilos usados pelo OpenOffice.org.

O Writer disponibiliza diversos tipos de estilos. Temos estilos de parágrafos, estilos de páginas, estilos de caracteres, estilos de numeração e estilos de molduras. Todos eles estão agrupados dentro da Família de Estilos.Família de Estilos

Estilos de Páginas ( estilo_1, estilo_2, ..., estilo_n )Estilos de Parágrafos ( estilo_1, estilo_2, ..., estilo_n )Estilos de Caracteres ( estilo_1, estilo_2, ..., estilo_n )Estilos de Molduras ( estilo_1, estilo_2, ..., estilo_n )Estilos de Numeração ( estilo_1, estilo_2, ..., estilo_n )

O serviço com.sun.star.style.StyleFamilies contém as famílias de estilos de um documento, para obter esta coleção faça:

Dim oFamiliasEstilos As Object oFamiliasEstilos = ThisComponent.getStyleFamilies()

Num documento texto, uma chamada ao método getElementNames () retorna um vetor com os nomes das seguintes famílias:

CharacterStyles - estilos de caracteres



ParagraphStyles - estilos de parágrafosFrameStyles - estilos de moldurasPageStyles - estilos de páginasNumberingStyles - estilos de numeração

O serviço com.sun.star.style.StyleFamily contém os estilos de uma mesma família, para obter esta coleção, use o acesso nomeado, isto é, getByName (“nomeDaFamília”):

oEstParagrafos = ThisComponent.StyleFamilies.getByName(“ParagraphStyles”)

O serviço com.sun.star.style.Style define as características de um estilo, para obter um estilo acesse-o pelo seu índice, por exemplo, se o objeto oEstParagrafos foi definido, como acima:

oEstilo = oEstParagrafos (1)

retorna o segundo estilo dentro da coleção de estilos de parágrafos.

A API do OpenOffice.org provê interfaces para facilitar o acesso a elementos de uma dada coleção. Ao trabalhar com estilos precisamos conhecer os métodos:

con.sun.star.container.XNameAcess

getByName (sNome As String ) As VariantgetElementNames ( ) As aStrings ( )hasByName ( sNome As String ) As Boolean

con.sun.star.container.XIndexAcess

getCount ( ) As LonggetByIndex ( nIndice As Long ) As Variant

con.sun.star.container.XNameContainer

insertByName ( sNome As String, oElemento As Variant) removeByName ( sNome As String )

O serviço com.sun.star.style.PageStyle define as propriedades mais comuns da página, abaixo temos algumas delas:

Propriedade DescriçãoBackColor Valor Long da cor de fundo da página

LeftMargin Valor Long da margem esquerda em 1/100 mm

RightMargin Valor Long da margem direita em 1/100 mm

TopMargin Valor Long da margem superior em 1/100 mm

BottomMargin Valor Long da margem inferior em 1/100 mm

IsLandscape Determina se o formato da página é paisagem (True / False)



PageStyleLayout Determina o “layout” da página (com.sun.star.style.PageStyleLayout)

Size Valores Long definindo o tamanho do papel (Size.Width e Size.Height)

Width Valor Long definindo a largura da página em 1/100 mm

Height Valor Long definindo a altura da página em 1/100 mm

HeaderLeftMargin Valor Long definindo a margem esquerda do cabeçalho em 1/100 mm

HeaderRightMargin

Valor Long definindo a margem direita do cabeçalho em 1/100 mm

HeaderIsOn Determina se o cabeçalho está ativo na página (True / False)

FooterLeftMargin Valor Long definindo a margem esquerda do rodapé em 1/100 mm

FooterRightMargin

Valor Long definindo a margem direita do rodapé em 1/100 mm

FooterIsOn Determina se o rodapé está ativo na página (True / False)

Vamos a um exemplo. Queremos exibir o número de estilos de páginas disponíveis num documento, os seus nomes e a propriedade Size do estilo de página Padrão (Standard). Os passos básicos são:

a) obter as familias de estilos do documento;

b) obter os estilos de páginas;

c) obter o vetor com os nomes dos estilos de páginas;

d) usar um índice para extrair cada um dos nomes;

e) obter a página padrão, usando o acesso nomeado.

A sub-rotina Sub exibeEstilosPagina, a seguir, implementa o nosso exemplo:

Sub exibeEstilosPagina Dim oDoc As Object Dim oFamiliaEstilos As Object Dim oEstilosPagina As Object Dim oPaginaPadrao As Object Dim mNomesEstilosPagina As Variant Dim sEstilo As String Dim sMsg As String

oDoc = ThisComponent ' obtém a Família de Estilos (note o uso de oDoc) oFamiliaEstilos = oDoc.StyleFamilies ' obtém os Estilos de Página oEstilosPagina = oFamiliaEstilos.getByName("PageStyles") ' exibe quantidade de estilos de página



MsgBox oEstilosPagina.Count ' obtém e exibe os nomes dos estilos de páginas mNomesEstilosPagina = oEstilosPagina.getElementNames() For n = LBound(mNomesEstilosPagina) To UBound(mNomesEstilosPagina) sMsg=sMsg + mNomesEstilosPagina(n) + " " Next n MsgBox sMsg,0,"Estilos de Páginas" ' obtém o Estilo de página Padrão (Standard) oPaginaPadrao = oEstilosPagina.getByName("Standard") ' testando o tamanho da página lLPag = oPaginaPadrao.Size.Width lAPag = oPaginaPadrao.Size.Height MsgBox Str$(lLPag) + " " + Str$(lAPag)

End Sub

A destacar, o acesso pelo índice dentro do laço For ... Next, o acesso nomeado ao estilo da página “Standard” e o acesso à propriedade Size.

Note, ainda, a chamada ao método getStylesFamilies ( ):

oFamiliaEstilos = oDoc.StylesFamiliesno OpenOffice.org Basic você pode omitir o get e o set ao programar propriedades.

Este exemplo pode ser usado como modelo para diversas operações com estilos.

Durante a formatação de texto, é comum a criação e aplicação de novos estilos. Esta é uma tarefa simples de executar dentro de uma macro. Para isto devemos seguir os passos:

a) Obter as famílias de estilos do documento;

b) Obter a família do grupo aonde será criado o novo estilo;

c) Criar uma instância do objeto do novo estilo;

d) Acrescentar o novo estilo ao grupo;

e) Definir as propriedades do novo estilo;

f) Aplicar o novo estilo.

Vamos retomar a sub-rotina Sub processaTexto e acrescentar código fonte para criar e aplicar um novo estilo de parágrafo. Digite (ou copie e cole) o código abaixo, após a última linha da Sub processaTexto, execute a macro e observe as definições de estilo do primeiro parágrafo do documento.

' ----------------------- ' código para novo estilo ' ----------------------- Dim oFamiliasEstilos As Object Dim EstilosParagrafo As Object Dim oNovoEstilo As Object ' obtem as familias de Estilos oFamiliasEstilos = oDoc.StyleFamilies ' obtem os estilos de parágrafos



EstilosParagrafo = oFamiliasEstilos.getByName("ParagraphStyles") ' cria um novo estilo de paragrafo oNovoEstilo = oDoc.createInstance("com.sun.star.style.ParagraphStyle") ' acrescenta o novo estilo com o nome "novo_estilo" EstilosParagrafo.insertByName("novo_estilo",oNovoEstilo) ' define as propriedades do estilo oNovoEstilo.Name = "novo_estilo" oNovoEstilo.CharFontName = "Arial" oNovoEstilo.CharHeight = 16 oNovoEstilo.ParaAdjust = com.sun.star.style.ParagraphAdjust.CENTER oNovoEstilo.CharWeight = com.sun.star.awt.FontWeight.BOLD ' entao, aplica o novo estilo ao primeiro paragrafo oCursor.gotoStart(FALSE) oCursor.gotoEndOfParagraph(TRUE) oCursor.paraStyleName = "novo_estilo"

Acima, deve-se notar a criação de um novo objeto, no caso uma instância de um estilo de parágrafo, com a chamada ao método createInstance ( ... ). E, ainda, as definições das propriedades do novo estilo.

6.6 Obtendo o objeto selecionado

A API do OpenOffice.org permite que uma macro extraia o conteúdo de uma seleção para, em seguida, aplicar alguma ação sobre o mesmo. A interface com.sun.star.frame.XModel provê o método abaixo, que retorna um ou mais objetos com a seleção atual do controlador corrente:

getCurrentSelection ( ) As ObjectO objeto retornado é do tipo com.sun.star.uno.XInterface e depende do conteúdo da seleção.

Conteúdo da seleção

Objeto retornado

Texto Um ou mais objetos apontando para TextRange

Células de tabela Um objeto apontando para um cursor de tabela

Caixa de texto Um objeto apontando para uma caixa de texto

Gráfico Um objeto apontando para um gráfico

Desenho Um ou mais objetos apontando para ShapeCollection

Para seleção de texto, o método getCurrentSelection ( ) opera da seguinte forma,:

a) se nada estiver selecionado, retorna um objeto TextRange com a posição do cursor da vista;

b) numa seleção simples, retorna um objeto TextRange com a seleção;

c) numa seleção múltipla, retorna objetos TextRange para o cursor da vista e para cada uma das seleções.

No exemplo abaixo, obtemos as cadeias selecionadas, uma ou mais se múltipla seleção, e mudamos a cor de cada uma para vermelha:



Sub processaSelecao Dim oDoc As Object Dim oSel As Object Dim oCurTxt As Object oDoc = ThisComponent oSel = oDoc.getCurrentSelection() For i = 0 To oSel.Count-1 oCurTxt = oSel(i) oCurTxt.CharColor = RGB(255,0,0) Next i MsgBox oSel.CountEnd Sub

Note o acesso aos objetos selecionados através de um índice e a criação de um cursor de texto antes da mudança de cor.

Para extrair a cadeia selecionada, chame o método getString ( ), como abaixo:

sCadeia = oSel ( i ).getString ( )

O método getString ( ) retorna uma cadeia vazia para o primeiro objeto nos casos a) e c) acima. Insira o código abaixo no laço For ... Next de processaSelecao e observe a saída:

MsgBox Str$ ( i ) + “: “ + oSel ( i ).getString ( )

Se você quiser aplicar alguma ação na palavra sob o cursor da vista, faça:

If Len(oSel(0).getString())= 0 Then oCurTxt = oSel(0).Text.createTextCursorByRange(oSel(0).getStart()) oCurTxt.gotoStartOfWord(False) oCurTxt.gotoEndOfWord(True) End If

Analise como se dá a criação do cursor de texto. Em seguida, como exercício, faça com que a Sub processaSeleção aplique a cor também na palavra sob o cursor da vista.

A API do OpenOffice.org tem, ainda, a interface com.sun.star.view.XSelectionSupplier, que implementa alguns métodos de seleção pela interface gráfica, entre eles:

select ( oObjeto As Object ) As Booleanse possível, seleciona o objeto oObjeto na interface gráfica

getSelection ( ) oObjeto As Variant obtém a seleção na interface gráfica, pode retornar um objeto ou uma coleção de objetos

Estes métodos podem ser chamados através do controlador corrente do modelo (veja o trecho de código abaixo).

Existem, ainda, dois métodos que podem ser úteis para a identificação do conteúdo selecionado, são eles:

getImplementationName ( ) As Stringretorna o nome da implementação do objeto

getName ( ) As Stringretorna o nome do objeto, se o mesmo for nomeado, caso de gráficos e tabelas.



Dim oControlador As Object oControlador = oDoc.getCurrentController() oSel = oControlador.getSelection() sNomeImpl = oSel.getImplementationName() sNome = oSel.getName()

Agora, altere a Sub processaSelecao, para alertar o usuário quando ele selecionar algo diferente de texto (dica, use getImplementationName).

6.7 Localizando objetos

Um documento do Writer pode conter outros objetos além de texto, como gráficos, tabelas, campos, caixas de texto, etc. Para cada tipo existe uma interface com métodos que retornam um recipiente com os objetos existentes no documento. Eis alguns:

getTextTables ( ) As <com.sun.star.container.XNameAccess >getTextFrames ( ) As <com.sun.star.container.XNameAccess >getGraphicObjects ( ) As <com.sun.star.container.XNameAccess >getTextSections ( ) As <com.sun.star.container.XNameAccess >getBookMarks ( ) As <com.sun.star.container.XNameAccess >getTextFields ( ) As <com.sun.star.container.XEnumerationAccess >getFootNotes ( ) As <com.sun.star.container.XIndexAccess >getEndNotes ( ) As <com.sun.star.container.XIndexAccess >getDocumentIndexes ( ) As <com.sun.star.container.XIndexAccess >

A interface XNameAccess implementa os seguintes métodos:

getByName (sNomeDoObjeto As String ) As Variant retorna o objeto nomeado

getElementNames ( ) As String ()retorna uma sequência de cadeias com os nomes dos objetos da coleção

hasByName ( sNome As String ) As Booleanretorna True se o objeto de nome sNome existe na coleção

A interface XIndexAccess define os métodos a seguir:

getByIndex ( iIndice As Long ) As Object retorna o objeto na posiçao iIndice da coleção

getCount ( ) As Longretorna o número de objetos da coleção

A interface XEnumerationAccess define o método:

createEnumeration ( ) As Object <com.sun.star.container.XEnumeration> retorna um objeto XEnumeration

A interface XEnumeration implementa os métodos abaixo:

hasMoreElements ( ) As Booleanretorna True se ainda existem elementos no recipiente



nextElement ( ) As Variantretorna o próximo elemento

A localização é simples, basta chamar o método apropriado e a seguir, usar o acesso nomeado ou indexado para obter o objeto.

A sub-rotina Sub localizaGraficos, abaixo, exibe os nomes de todos os objetos gráficos do documento:

Sub localizaGraficos

Dim oGraficos As Object Dim oGrafico As Object Dim n As Integer

oGraficos = ThisComponent.getGraphicObjects() For n = 0 To oGraficos.Count -1 oGrafico = oGraficos (n) MsgBox oGrafico.getName() Next n MsgBox "Gráficos no documento: " + Str$(oGraficos.Count)

End Sub

Para apagar um gráfico do seu documento, você pode usar o bloco de código:

oGrafico = oGraficos.getByName (“Gráfico2”) oGrafico.dispose ()

No exemplo a seguir, que demonstra a criação de uma enumeração, exibimos o comando de cada um dos campos de um documento:

Sub localizaCampos

Dim oCampos As Object Dim oCampo As Object Dim n As Integer

oCampos = ThisComponent.getTextFields().createEnumeration() n = 0 Do While (oCampos.hasMoreElements()) oCampo = oCampos.NextElement() MsgBox oCampo.getPresentation(True) n = n + 1 Loop MsgBox "Campos no documento: " + Str$(n)

End Sub

Observe que a criação e o acesso aos elementos de uma enumeração é sequêncial e não indexado ou nomeado. O método getPresentation() retorna o conteúdo do campo se o parâmetro for False.



Geralmente, para recuperar o objeto que nos interessa dentro da coleção retornada por um dos métodos acima, precisamos conhecer o seu nome ou a sua posição dentro da coleção.

6.8 Busca e Substituição

A API do OpenOffice.org tem mecanismos avançados para a busca e substituição de texto num documento.

Para localizar e substituir texto devemos: criar um descritor de busca ou substituição; definir as propriedades e chamar o método apropriado.

A interface com.sun.star.util.XSearchable provê os métodos abaixo para busca:

createSearchDescriptor ( ) As Object <SearchDescriptor>cria um descritor de busca para receber as propriedades da busca.

FindAll ( oDescritor As Object ) As Object <com.sun.star.container.XIndexAccess>retorna uma coleção de TextRanges com todos os resultados da busca

FindFirst ( oDescritor As Object ) As Object <com.sun.star.uno.XInterface>retorna um TextRange com o primeiro resultado da busca

FindNext ( oInicio As Object, oDescritor As Object ) As Object <XInterface> retorna um TextRange com o próximo resultado da busca. O parâmetro oInicio é ponto de partida para a busca, normalmente o resultado da última chamada a FindFirst ou FindNext.

O serviço SearchDescriptor tem os métodos abaixo:

getSearchString ( ) As Stringobtém a cadeia de busca

setSearchString ( sCadeia As String )define a cadeia de busca

Eis algumas de suas propriedades:

Propriedade DescriçãoSearchBackwards Se True busca para o início do documento

SearchCaseSensitive Se True considera maiúsculas / minúsculas

SearchWords Se True busca palavras completas

SearchStyles Se True busca por um estilo

No exemplo a seguir, vamos localizar, no documento, todas as ocorrências da cadeia “( )” e trocar a cor da fonte para vermelha. Digite (ou copie e cole) o código abaixo e execute a sub-rotina.

Sub buscaTodas Dim oDoc As Object Dim oDescBusca As Object oDoc = ThisComponent



oDescBusca = oDoc.createSearchDescriptor() oDescBusca.SearchWords = True oDescBusca.setSearchString ("( )") oResultado = oDoc.findAll( oDescBusca ) For n% = 0 To oResultado.Count - 1 oResultado(n%).CharColor = RGB(255,0,0) Next MsgBox "Ocorrências de "+oDescBusca.getSearchString()+ _ “ “ + Str$(oResultado.Count)End Sub

A tarefa acima pode, também, ser executada com os métodos findFirst e findNext:

oResultado = oDoc.findFirst( oDescBusca ) Do Until IsNull(oResultado) oResultado.CharColor = RGB(250,100,50) oResultado = oDoc.findNext(oResultado, oDescBusca ) Loop

A substituição de texto é implementada pela interface XReplaceable, que herda as características de XSearchable. Ela provê os métodos:

createReplaceDescriptor ( ) As Object <com.sun.star.util.XReplaceDescriptor>retorna um descritor de substituição para as propriedades

replaceAll ( xDescritor As Object <com.sun.star.util.XReplaceDescriptor>) As Long busca e substitui todas as ocorrências, retorna o total de substituições

O serviço ReplaceDescriptor tem métodos para as propriedades da cadeia:

getReplaceString ( ) As Stringobtém a cadeia substituta

setReplaceString ( sCadeia As String )define a cadeia substituta

Eis um exemplo simples de busca e substituição:

Sub substituiTodas Dim oDoc As Object Dim oDescritor As Object

oDoc = ThisComponent oDescritor = oDoc.createReplaceDescriptor() oDescritor.setSearchString( "( )" ) oDescritor.setReplaceString( "()" ) n = oDoc.replaceAll(oDescritor) MsgBox n

End Sub



Note que não temos um método para substituição interativa. Porém, através da busca e edição, é possível implementar, com facilidade, este procedimento.

6.9 Inserindo objetos

Vamos abordar, rapidamente, outra tarefa comum em processamento de textos. A inserção de objetos de origem externa, como gráficos e documentos, num documento do Writer.

Inserir um documento texto é muito fácil, basta criar um cursor de texto e chamar o método:

insertDocumentFromURL ( sURL As String, mPropriedades ( ) As Object )Os parâmetros deste método são idênticos aos já vistos na seção Carregando Documentos.

Dim oCursorTxt As Object Dim mPropriedades ( ) Dim sURL As String oCursorTxt = ThisComponent.createTextCursor ( ) ' sURL = “caminho_completo_do_arquivo” oCursorTxt.insertDocumentFromURL ( sURL, mPropriedades() )

Para inserir na posição do cursor da interface gráfica, crie o cursor de texto a partir do cursor da vista.

A inserção de arquivos gráficos é um pouco mais complicada, para isso você deve:

a) criar um objeto gráfico;

b) definir as suas propriedades;

c) inserir o objeto.

Observe a sub-rotina Sub inserirGrafico a seguir:

Sub inserirGrafico Dim oTxt As Object Dim oCursorTxt As Object Dim oGrafico As Object Dim sURL As String oTxt = ThisComponent.getText() oCursorTxt = oTxt.createTextCursor() oGrafico = ThisComponent.createInstance("com.sun.star.text.GraphicObject") sURL = "file:///D:/NAD/OPENOFFICE/HOWTO/FIGURAS/DIALOGO.JPG" oGrafico.GraphicURL = sURL oGrafico.AnchorType = com.sun.star.text.TextContentAnchorType.AT_PARAGRAPH oTxt.insertTextContent(oCursorTxt.getStart(), oGrafico, False)End Sub

A chamada ao método createInstance ( ) cria o objecto gráfico, depois definimos as propriedades GraphicURL e AnchorType e, finalmente, inserimos o gráfico chamando o método insertTextContent ( ) com os parâmetros adequados.

A propriedade AnchorType pode assumir, ainda, os seguintes valores: AT_CHARACTER, AT_PAGE e AS_CHARACTER.



O API do OpenOffice.org (versão 1.0.1) salva no documento apenas a URL do gráfico. Logo, se você removê-lo da sua localização original, o Writer não terá como encontrá-lo.

6.10 Tabelas

Uma tabela é um conjunto de células organizadas por linhas e colunas, onde cada célula tem um nome, normalmente indicado por letras e números. As letras referem-se às colunas e os números às linhas. Contudo, se existirem células mescladas ou divididas, o conceito de coluna poderá desaparecer e o esquema de nomeação torna-se complicado.

Uma célula pode conter texto simples (cadeias e números), gráficos, fórmulas e campos com várias características de formatação.

Uma tabela recebe um nome único no documento, podendo servir como origem para gráficos, ter o seu contéudo ordenado e ser automaticamente formatada.

A API do OpenOffice.org tem diversos serviços e interfaces para lidar com tabelas, vejamos as principais.

A interface com.sun.star.text.XTextTable encarrega-se do gerenciamento de tabelas num documento e contém os métodos abaixo:

initialize ( nLinhas As Long, nColunas As Long)Inicializa uma tabela, recebe o número de linhas e colunas como parâmetros.

getCellNames ( ) As Object < Strings >Obtém os nomes das células, retorna um conjunto de cadeias

getCellByName ( sNomeCelula As String ) As Object < com.sun.star.table.XCell >Obtém a célula nomeada no parâmetro, retorna um objeto XCell

getRows ( ) As Object < com.sun.star.table.XTableRows >Obtém as linhas da tabela, retorna um objeto para XTableRows.

getColumns ( ) As Object < com.sun.star.table.XTableColumns >Obtém as colunas da tabela, retorna um objeto para XTableColumns.

createCursorByCellName ( sNomeCelula As String ) As Object < XTextTableCursor >Cria um cursor de tabela posicionado na célula nomeada no parâmetro

O serviço TextTable possui diversas propriedades, eis algumas delas:

Propriedade DescriçãoLeftMargin Contém a margem esquerda da tabela, valor Long

RightMargin Contém a margem direita da tabela, valor Long

Split Um valor False impede a divisão da tabela em duas páginas

TableBorder Contém a descrição da borda da tabela

TableColumnSeparators

Contém a descrição dos separadores de colunas da tabela



BackGraphicURL Contém a URL do gráfico de fundo da célula

As interfaces XTableRows e XtableColumns, retornadas pelos métodos getRows () e getColumns (), acima, possuem os métodos a seguir:

insertByIndex ( nIndice As Long, nTotal As Long )removeByIndex ( nIndice As Long, nTotal As Long )getElementType ( ) As TypehasElements ( ) As BooleangetByIndex ( ) As VariantgetCount ( ) As Long

A interface XTextTableCursor, retornada pelo método createCursorByCellName, acima, provê os métodos:

getRangeName ( ) As StringRetorna a extensão de células do cursor, isto é, os nomes das células superior esquerda e inferior direita, por exemplo A2:D25 (note o separador : ).

goLeft ( nQuant As Integer, bExpande As Boolean ) As BooleangoRight ( nQuant As Integer, bExpande As Boolean ) As BooleangoUp ( nQuant As Integer, bExpande As Boolean ) As BooleangoDown ( nQuant As Integer, bExpande As Boolean ) As BooleangotoStart ( bExpande As Boolean )gotoEnd ( bExpande As Boolean )Métodos para movimentação e seleção, nQuant é a quantidade de células e, se bExpande for True, extende a seleção durante o deslocamento do cursor.

gotoCellByName (sNome As String, bExpande As Boolean ) As BooleanDesloca o cursor para a célula nomeada no parâmetro.

mergeRange ( ) As BooleansplitRange ( nQuant As Integer, bHoriz As Boolean ) As BooleanMétodos para fundir e dividir células.

Através do serviço TextTableCursor podemos efetuar a formatação das células, pois, ele inclui os serviços CharacterProperties e ParagraphProperties.

A interface com.sun.star.table.XCellRange define os métodos abaixo para lidar com extensões de células:

getCellByPosition ( nColuna As Long, nLinha As Long ) As Object < XCell >getCellRangeByPosition ( nEsq, nSup, nDir, nInf ) As Object < XCellRange >getCellRangeByName ( sRange As String ) As Object < XCellRange >

O serviço com.sun.star.table.CellRange inclui com.sun.star.table.CellProperties, que define as propriedades de uma ou mais células. Eis algumas:

Propriedade Descrição



CellBackColor Valor Long com a cor de fundo da célula

HoriJustify Alinhamento horizontal do conteúdo da célula (enum CellHoriJustify)

VertJustify Alinhamento vertical do conteúdo da célula (enum CellVertJustify)

IsTextWrapped Se True, o texto muda de linha automaticamente

Orientation Orientação do conteúdo da célula (enum CellOrientation)

RotateAngle Define a rotação do conteúdo da célula (em 1/100 graus)

TableBorder Descreve a borda das células (struct TableBorde)

TopBorder Descreve a borda superior de cada célula (struct BorderLine)

BottomBorder Descreve a borda inferior de cada célula (struct BorderLine)

LeftBorder Descreve a borda esquerda de cada célula (struct BorderLine)

RightBorder Descreve a borda direita de cada célula (struct BorderLine)

NumberFormat Índice do formato numérico usado nas células (serviço NumberFormatter)

CellProtection Descreve a proteção da célula (serviço CellProtection)

A interface com.sun.star.table.XCell oferece os métodos abaixo para manipular o conteúdo de uma célula:

getFormula ( ) As String setFormula ( sFormula As String )métodos para obter ou definir a fórmula de uma célula

getValue ( ) As DoublesetValue ( nValor As Double )métodos para obter ou definir o valor de uma célula

getType ( ) As Long < com.sun.star.table.CellContentType >retorna o tipo do conteúdo de uma célula, como enumerado em CellContentType

getError ( ) As Longretorna o erro de uma célula, útil para rastrear erros em fórmulas

O nome de uma tabela pode ser obtido ou definido com os métodos a seguir, da interface com.sun.star.container.XNamed:

getName ( ) As StringsetName ( sNomeTabela As String )

O conteúdo de uma tabela pode ser ordenado com a interface com.sun.star.util.XSortable e seus métodos:

createSortDescriptor ( ) As Variant <com.sun.star.beans.PropertyValue> retorna um descritor para as propriedades da ordenação



sort (xDescritor As Variant <com.sun.star.beans.PropertyValue> )executa a ordenação conforme o descritor

Seguem algumas das propriedades do descritor de ordenação (SortDescriptor):

Propriedade DescriçãoIsCaseSensitive Se True, considera maiúsculas / minúsculas

SortAscending Define a ordem da ordenação (??)

SortColumns Se True ordena as colunas, senão ordena as linhas.

O serviço com.sun.star.table.TableSortDescriptor inclui o serviço SortDescriptor e possui as propriedades abaixo:

Propriedade DescriçãoSortFields Descreve os campos de ordenação

<com.sun.star.util.SortField>

MaxFieldCount Define o número máximo de campos, somente leitura

Orientation Define a orientação da ordenação <com.sun.star.table.TableOrientation>

ContainsHeader Se True, não ordena a primeira linha ou coluna

É hora de apresentar um exemplo. Inicialmente, vamos criar, inicializar e inserir uma tabela, com cinco linhas e três colunas, no início do documento corrente. Depois, vamos definir os títulos das colunas. Digite o código abaixo, execute e observe o resultado:

Sub criaTabela Dim oTxt As Object Dim oTab As Object ' ' cria, inicializa e insere a tabela no inicio do documento oTxt = ThisComponent.getText() oTab = ThisComponent.createInstance("com.sun.star.text.TextTable") oTab.initialize(5,3) oTxt.insertTextContent(oTxt.createTextCursor(), oTab, FALSE) ' ' preenche os títulos das colunas (células A1, B1 e C1 ) Dim oCelula As Object oCelula = oTab.getCellByName("A1") oCelula.setString("Coluna A") oCelula = oTab.getCellByName("B1") oCelula.setString("Coluna B") oCelula = oTab.getCellByName("C1") oCelula.setString("Coluna C")End Sub

Primeiro criamos o objeto tabela com createInstance (), depois definimos as linhas e colunas com initialize (), inserimos a tabela no documento com uma chamada ao método



insertTextContent ( ) e, então , obtemos cada uma das células do cabeçalho e definimos o seu conteúdo.

O bloco de código abaixo demonstra o emprego do cursor de tabela, navegação, formatação e mesclagem de células. Acrescente-o à Sub criaTabela.

' ' cria um cursor de tabela na célula CellNames(0) = A1 Dim oCurTab As Object oCurTab = oTab.createCursorByCellName(oTab.CellNames(0)) ' seleciona as células A1, B1 e C1 oCurTab.gotoStart(False) oCurTab.goRight(2, True) ' Aplica o estilo de parágrafo Título na seleção oCurTab.paraStyleName = "Heading" ' exibe o nome da extensão selecionada (range) ' Note a forma de apresentação (invertida) MsgBox oCurTab.getRangeName() ' ' nomeia as celulas a partir da linha 2 e ' escreve número da linha na coluna C Dim sNomes() As Variant Dim sNomeCelula As String sNomes = Array("A","B","C") For i% = 1 To 4 For j% = 1 To 3 sNomeCelula = sNomes(j%-1)+ Str$(i%+1) oCelula = oTab.getCellByName(sNomeCelula) If (j% - 1 = 2) Then ' define um valor numérico para a célula oCelula.setValue(i% + 1) Else oCelula.setString(sNomeCelula) End If Next j% Next i% ' ' define uma fórmula (soma de C2 até C4) para a célula C5 oCelula = oTab.getCellByName("C5") oCelula.setFormula("sum <C2:C4>") ' ' funde as células A5 e B5 e muda seu conteúdo oCurTab.gotoCellByName("A5", False) oCurTab.goRight(1, True) oCurTab.mergeRange() oCelula = oTab.getCellByName("A5") oCelula.setString("Total")

Note a criação do cursor da tabela com createCursorByCellNames (...), o uso do cursor para formatação, o uso dos métodos setValue () e setFormula () e a seleção e mesclagem das células A5 e B5.

No próximo bloco de código, veremos a ordenação de uma extensão de células (A2:C4) da nossa tabela. Basta inserir o código na Sub criaTabela e executar para ver o resultado.



' ' ordena de A2 até C4 Dim oCampoOrd(0) As New com.sun.star.util.SortField Dim oDescrOrd As Variant Dim oExtensao As Object ' ' define a extensão a ser ordenada oExtensao = oTab.getCellRangeByName("A2:C4") ' define o campo de ordenação e suas propriedades oCampoOrd(0).Field = 0 oCampoOrd(0).SortAscending = False oCampoOrd(0).FieldType = com.sun.star.util.SortFieldType.ALPHANUMERIC ' cria o descritor de ordenação oDescrOrd = oTab.createSortDescriptor() ' define as propriedades do descritor oDescrOrd(0).Name = "SortFields" oDescrOrd(0).Value = oCampoOrd() oDescrOrd(1).Name = "ContainsHeader" oDescrOrd(1).Value = False oDescrOrd(2).Name = "SortColumns" oDescrOrd(2).Value = False ' ordena a extensão oExtensao.sort(oDescrOrd())

Note que iniciamos com a declaração das variáveis, criamos uma extensão de células com uma chamada ao método getCellRangeByName (), definimos as propriedades do campo de ordenação, criamos o descritor e definimos as suas propriedades (o campo de ordenação é uma propriedade do descritor) e, finalmente, invocamos o método sort () para executar a sua tarefa.

Antes de terminar esta seção, vejamos como se dá o acesso às tabelas existentes num documento texto. O processo é o mesmo já visto na seção Localizando Objetos.

O método getTextTables () da interface XTextTablesSupplier retorna uma coleção contendo as tabelas do documento. Ele percorre o documento do início para o final.

getTextTables () As Object <com.sun.star.container.XNameAccess>

O exemplo abaixo demonstra a localização das tabelas de um documento, depois obtém as coleções de linhas e colunas da tabela com o nome “Tabela3”.

Sub localizaTabelas Dim oTabelas As Object Dim oTabela As Object Dim oLinhas As Object Dim oColunas As Object Dim n As Integer

oTabelas = ThisComponent.getTextTables() For n = 0 To oTabelas.Count -1 oTabela = oTabelas.getByIndex(n) MsgBox oTabela.getName() Next n



MsgBox "Tabelas no documento: " + Str$(oTabelas.Count) ' If (oTabelas.hasByName (“Tabela3”)) Then oTabela = oTabelas.getByName("Tabela3") oLinhas = oTabela.getRows() oColunas = oTabela.getColumns() MsgBox Str$(oLinhas.Count)+" - "+Str$(oColunas.Count) End IfEnd Sub

Lembre-se que, para acessar uma tabela, você deve conhecer o seu nome ou o seu índice dentro da coleção e, em seguida, chamar o método getByName () ou getByIndex ().

Após obter a tabela desejada, use as técnicas já apresentadas para editar o seu conteúdo.

6.11 Desenhos

A API do OpenOffice.org possui diversos serviços e interfaces para operações com desenhos num documento, através de uma macro. Nesta seção, veremos como usar alguns destes serviços e interfaces.

O serviço com.sun.star.text.Shape, contém muitas propriedades relacionadas aos objetos de desenho, seguem algumas delas:

Propriedade DescriçãoAnchorType Tipo da âncoraHoriOrient Orientação horizontalVertOrient Orientação vertical

LeftMargin Margem esquerda

RightMargin Margem direita

TopMargin Margem superior

BottomMagin Margem inferior

O serviço com.sun.star.drawing.Shape contém proriedades adicionais, como Name, que permite definir um nome para o desenho, e suporta as interfaces:

com.sun.star.beans.XPropertySet com.sun.star.drawing.XShape com.sun.star.drawing.XShapeDescriptor

A interface XShape, acima, provê métodos para definir a posição e o tamanho do desenho:

getPosition ( ) As Object < com.sun.star.awt.Point > setPosition ( Ponto As Object < com.sun.star.awt.Point > ) getSize ( ) As Object < com.sun.star.awt.Size > set Size ( Tamanho As Object < com.sun.star.awt.Size > )



A interface XShapeDescriptor contém o método a seguir, que retorna uma cadeia com o tipo de desenho:

getShapeType ( ) As String

Através da interface com.sun.star.lang.XMultiServiceFactory, criamos o objeto desenho usando o método:

createInstance ( sServico As String ) As Object < com.sun.star.uno.XInterface >

O módulo com.sun.star.drawing da API do OpenOffice.org contém diversos serviços para a criação de objetos de desenho e são usados como parâmetro da função createInstance ( ). Estes serviços contém, além de propriedades comuns, outras específicas. Eis alguns deles:

com.sun.star.drawing.EllipseShape usado para desenhar círculos e elipses com.sun.star.drawing.RectangleShape usado para desenhar retângulos com.sun.star.drawing.LineShape usado para desenhar linhas

A interface com.sun.star.drawing.XShapes define métodos para adicionar e remover desenhos do documento:

add ( Desenho As Object < com.sun.star.drawing.Shape > ) remove ( Desenho As Object < com.sun.star.drawing.Shape > )

A interface com.sun.star.text.XText também define os métodos abaixo, apresentados noutras seções, para adicionar e remover desenhos do documento:

insertTextContent ( ) removeTextContent ( )

A interface com.sun.star.drawing.XDrawPageSupplier define o método abaixo para obter a página de desenho do documento:

getDrawPage ( ) As Object < com.sun.star.drawing.DrawPage >

Para a manipulação de desenhos no Writer e Calc, o OpenOffice.org utiliza os mecanismos básicos de desenho do Draw. Uma das principais diferenças, é que no Draw existem várias páginas de desenho, enquanto no Writer existe apenas uma.

Vejamos como inserir desenhos num documento, através de uma macro que usa alguns dos métodos e propriedades apresentados. Crie um documento do Writer e digite o código fonte abaixo no IDE Basic, em seguida execute a macro e observe o resultado.

Sub criaDesenho' Dim oDoc As Object Dim oTexto As Object Dim oCursor As Object Dim oRetang As Object



Dim oElipse As Object Dim oPagDes As Object Dim oTamanho As New com.sun.star.awt.Size Dim oPonto As New com.sun.star.awt.Point oDoc = ThisComponent oTexto = oDoc.getText() oCursor = oTexto.createTextCursor() ' insere dois novos parágrafos no final do texto oCursor.gotoEnd(False) oTexto.insertControlCharacter(oCursor, _ com.sun.star.text.ControlCharacter.PARAGRAPH_BREAK, False) oTexto.insertControlCharacter(oCursor, _ com.sun.star.text.ControlCharacter.PARAGRAPH_BREAK, False) oCursor.gotoPreviousParagraph(False) ' cria um objeto retângulo e um objeto elipse oRetang = oDoc.createInstance("com.sun.star.drawing.RectangleShape") oElipse = oDoc.createInstance("com.sun.star.drawing.EllipseShape") ' define o tamanho do retângulo e elipse oTamanho.Height = 4000 oTamanho.Width = 10000 oRetang.setSize(oTamanho) oRetang.Name = "Ret_1" oTamanho.Height = 3000 oTamanho.Width = 6000 oElipse.setSize(oTamanho) oElipse.Name = "Eli_1" ' define a posição do retângulo a direita da elipse oPonto.X = 6100 oPonto.Y = 0 oRetang.setPosition (oPonto) ' define a âncora no parágrafo oRetang.AnchorType = com.sun.star.text.TextContentAnchorType.AT_PARAGRAPH oElipse.AnchorType = com.sun.star.text.TextContentAnchorType.AT_PARAGRAPH ' insere na posição do cursor de texto oTexto.insertTextContent(oCursor,oElipse,FALSE) oTexto.insertTextContent(oCursor,oRetang,FALSE) oPosRet = oRetang.getPosition() MsgBox Str$(oPosRet.X)+" - "+Str$(oPosRet.Y) ' cria uma linha oLinha = oDoc.createInstance( "com.sun.star.drawing.LineShape" ) ' define o tamanho da linha oTamanho.Height = 30 oTamanho.Width = 6000 oLinha.setSize (oTamanho) ' define a posição da linha oPonto.X = 6000 oPonto.Y = 10000 oLinha.setPosition (oPonto) ' obtém a página de desenho do documento oPagDes = oDoc.getDrawPage() ' adiciona a linha na primeira página oPagDes.add (oLinha)



'End Sub

Começamos inserindo parágrafos no final do texto, a seguir criamos dois objetos de desenho, um retângulo e uma elipse, definimos a suas propriedades e usamos o método insertTextContent ( ) para adicionar os objetos no documento. Depois, criamos uma linha, obtemos a página de desenho do documento e adicionamos a linha com o método add ( ).

Para encerrar esta seção, vejamos um exemplo que identifica os objetos de desenho existentes no nosso documento. Crie a macro abaixo num documento contendo desenhos, molduras e gráficos. Em seguida execute e observe a saída.

Sub obtemDesenhos'' obtem outros objetos além de desenhos, ex: molduras' Dim oDoc As Object Dim oPage As Object oDoc = ThisComponent oPage = oDoc.getDrawPage() sMsg = "" nNrDes = oPage.getCount()

For i = 0 To nNrDes - 1oShape = oPage.getByIndex ( i )' obtem nome se definido na criação'sMsg = sMsg + oShape.getName() + chr$(10)sMsg = sMsg + oShape.getShapeType() + chr$(10)

Next iMsgBox sMsg + Str$(nNrDes)

End Sub

Note que outros objetos baseados no serviço Shape, como molduras, também são identificados. O método getName ( ), somente retorna o nome, se o objeto foi nomeado durante a criação do desenho.


Documentos do Calc Versão 2

7 Documentos do Calc

7.1 Introdução

Um documento do Calc contém uma ou mais folhas de planilhas. Cada planilha é formada por células organizadas em linhas e colunas, de modo bem parecido com o de uma tabela do Writer. Estas células contém, basicamente, texto, que pode representar uma cadeia de caracteres, um valor numérico, um campo ou uma fórmula.

Cada um dos elementos acima (documento, planilha e célula), possui características próprias. Algumas podem ser alteradas, como por exemplo: estilo de página, formato numérico, parágrafo e fonte.

Além das tarefas comuns de edição, podemos aplicar, sobre o conteúdo de uma planilha operações como: ordenação, filtragem, sub-totalização, geração de gráficos, etc.

Podemos, também, inserir, numa planilha, objetos como imagens, desenhos, dados de uma fonte externa e objetos OLE.

Como você já deve ter notado, dado a riqueza e o poder das operações com documentos do Calc, a sua programação é um assunto extenso. Nas próximas seções, tentarei apresentar o básico.

7.2 Planilhas

As funções básicas já abordadas no capítulo Trabalhando com Documentos, podem ser usadas também com documentos do Calc. Assim, esta seção vai cobrir algumas operações sobre as folhas das planilhas de um documento do Calc.

O módulo com.sun.star.sheet, da API do OpenOffice.org, contém os principais serviços, interfaces e grupos de constantes relacionados com planilhas.

O serviço SpreadsheetDocument representa o modelo de um documento do Calc, contendo atributos e uma ou mais planilhas. A interface XSpreadsheetDocument provê o método getSheets (), que retorna uma coleção com as planilhas do documento.

getSheets ( ) As Object <com.sum.star.sheet.XSpreadsheets> Os objetos desta coleção podem ser acessados pelos seus nomes ou índices. Podemos, ainda, criar uma enumeração e usar o acesso seqüêncial.

A interface XSpreadsheets, retornada por getSheets (), define os métodos abaixo:

insertNewByName ( sNome As String, iPosicao As Integer )moveByName ( sNome As String, iDestino As Integer )copyByName ( sNomeOrigem As String, sNomeCopia As String, iPosicao As Integer )

Para fixar os conceitos acima, no exemplo a seguir, vamos criar um documento e efetuar algumas operações com planilhas.


Versão 2 Documentos do Calc

Sub criaDocCalc Dim oDesk As Variant Dim oDoc As Object Dim mProp() As Variant Dim sURL As String

' cria documento do Calc oDesk = createUnoService("com.sun.star.frame.Desktop") sUrl = "private:factory/scalc" oDoc = oDesk.LoadComponentFromURL(sUrl,"_blank",0,mProp()) ' exibe a propriedade casas decimais padrão do documento MsgBox oDoc.StandardDecimals ' ' navega pelas planilhas existentes no documento Dim oPlanilhas As Object Dim oPlanilha As Object Dim sMsg As String ' oPlanilhas = oDoc.getSheets() sMsg = "" For n=0 To oPlanilhas.Count - 1 oPlanilha = oPlanilhas.getByIndex(n) sMsg = sMsg + oPlanilha.getName() + Chr$(13) Next n MsgBox sMsg + Str$(oPlanilhas.Count) ' acesso nomeado If oPlanilhas.hasByName("Planilha2") Then oPlanilha = oPlanilhas.getByName("Planilha2") MsgBox oPlanilha.PageStyle End If ' insere uma folha no início oPlanilhas.insertNewByName("Planilha4",0) MsgBox oPlanilhas.Count ' move para o final oPlanilhas.moveByName("Planilha4",4)End Sub

Note os parâmetros para a criação do documento, o acesso aos objetos da coleção e o uso dos métodos para inserir e mover uma folha de planilha.

O serviço SpreadsheetView fornece funcionalidades relacionadas à vista corrente de um documento do Calc. Ele inclui o serviço SpreadsheetViewSettings, que define algumas propriedades de cada uma das planilhas do documento e, a sua interface XspreadsheetView, traz os métodos a seguir, para a definição da planilha ativa no documento:

getActiveSheet ( ) As Object < XSpreadsheet >setActiveSheet ( oPlanilha As Object < XSpreadsheet >)

Lembre-se que as operações relacionadas com a interface gráfica são gerenciadas pelo objeto controlador do documento.

Digite o código fonte abaixo no final da Sub criaDocCalc, execute e observe o resultado.



' ativa a Planilha4 na GUI If oPlanilhas.hasByName("Planilha4") Then MsgBox oDoc.getCurrentController().getActiveSheet().getName() oPlanilha = oPlanilhas.getByName("Planilha4") oDoc.getCurrentController().setActiveSheet(oPlanilha) End If

Inicialmente, exibimos o nome da planilha ativa e, então, selecionamos a planilha de nome Planilha4.

Como já demonstrado no capítulo Documentos do Writer, podemos alterar o conteúdo de um documento independente da interface gráfica.

7.3 Editando

Para editar o conteúdo de uma ou mais células, devemos ter em mente o seguinte:

a) obter a planilha onde se encontram as células a editar;

b) obter uma extensão contendo as células a serem editadas, este passo é opcional, pois uma planilha é uma extensão de células;

c) obter a célula a editar;

d) definir o conteúdo da célula.

O item a) deve ser solucionado com o uso do método getSheets (), associado ao acesso nomeado, indexado ou enumerado, como demonstrado na seção sobre Planilhas.

As ferramentas para solucionar os itens b), c) e d) também já foram apresentadas na seção sobre Tabelas e envolve os métodos das interfaces XCellRange e XCell.

Métodos da interface com.sun.star.table.XCellRange:

getCellByPosition ( nColuna As Long, nLinha As Long ) As Object < XCell >getCellRangeByPosition ( nEsq, nSup, nDir, nInf ) As Object < XCellRange >getCellRangeByName ( sRange As String ) As Object < XCellRange >

Devemos lembrar que a posição de uma célula, dentro de uma extensão (range), é relativa ao início da extensão.

Métodos da interface com.sun.star.table.XCell:

getFormula ( ) As String setFormula ( sFormula As String )getValue ( ) As DoublesetValue ( nValor As Double )getType ( ) As Long < com.sun.star.table.CellContentType >getError ( ) As Long

Para relembrar, vejamos um exemplo de edição do conteúdo das células de uma planilha. Digite o código abaixo, execute e observe o resultado.



Sub editaPlanilha Dim oDesk As Variant Dim oDoc As Object Dim mProp() As Variant Dim sURL As String ' ' cria documento do Calc oDesk = createUnoService("com.sun.star.frame.Desktop") sUrl = "private:factory/scalc" oDoc = oDesk.LoadComponentFromURL(sUrl, "_blank", 0, mProp()) ' ' edita células da planilha Dim oPlanilha As Object Dim oCelula As Object Dim sTitCol() As String ' escreve os titulos das colunas sTitCol = Array ("CÓDIGO","MATERIAL","QUANT","P. UNIT","P. TOTAL") oPlanilha = oDoc.getSheets().getByIndex(0) For i% = 0 To 4 oCelula = oPlanilha.getCellByPosition(i%, 0) oCelula.setString(sTitCol(i%)) Next i% ' ' preenche as células com texto, valor e formula For i% = 1 To 6 For j% = 0 To 4 oCelula = oPlanilha.getCellByPosition(j%, i%) If (j% = 0) Then If i% < 4 Then oCelula.setString("A" + Str$(i%)) Else oCelula.setString("A" + Str$(i%-3)) End If ElseIf (j% = 1) Then oCelula.setString("Material de construção " + Str$(i%)) ElseIf (j% = 2) Then oCelula.setValue(i% * j%) ElseIf (j% = 3) Then oCelula.setValue(100 * Rnd()) Else sLinha = Trim$(Str$(i%+1)) sFormula = "=C" + sLinha + " * " + "D" + sLinha oCelula.setFormula(sFormula) End If Next j% Next i% ' resumo oCelula = oPlanilha.getCellByPosition(0, 7) oCelula.setString("CUSTO TOTAL") ' sFormula = "=Sum(E1:E6)" oCelula = oPlanilha.getCellByPosition(4, 7)



oCelula.setFormula(sFormula) 'End Sub

Note que, na segunda chamada do método setFormula (), definimos a fórmula usando o nome de uma função em inglês. Para utilizar os nomes das funções exibidos pela interface gráfica, use a propriedade FormulaLocal, do serviço com.sun.star.sheet.SheetCell., por exemplo:

oCelula = oPlanilha.getCellByPosition(4, 7) sFormula = "=Soma(E1:E6)" oCelula.FormulaLocal = sFormula

O serviço SheetCell define as seguintes propriedades:

Propriedade DescriçãoPosition Somente leitura, posição da célula na planilha

Size Somente leitura, tamanho da célula em 1/100 mm

FormulaLocal Cadeia com o nome local da fórmula

FormulaResultType Somente leitura, tipo do resultado de uma fórmula

ConditionalFormat Definições de formatação condicional da célula

ConditionalFormatLocal

Definições locais de formatação condicional da célula

Validation Definições de validação da célula

ValidationLocal Definições locais de validação da célula

Na próxima seção, trataremos da criação e emprego de um cursor, outra funcionalidade dos documentos do Calc.

7.4 Navegando pelas Células

Uma célula ou extensão de células é identificada pelo seu endereço, que é formado pelos índices da planilha, coluna inicial, linha inicial, coluna final e linha final. A interface XCellRangeAddressable define o método abaixo, para a recuperação deste endereço:

getRangeAddress ( ) As Object < com.sun.star.table.CellRangeAddress >retorna uma estrutura CellRangeAddress com os elementos Sheet, StartColumn, StartRow, EndColumn e EndRow.

Numa planilha, também podemos criar um cursor. Este cursor é uma extensão de células com funcionalidades para navegação, formatação e edição, dentre outras.

O serviço Spreadsheet, através da interface XSpreadsheet, define os métodos a seguir, para a criação de um cursor de células:

createCursor ( ) As Object < XSheetCellCursor > retorna um cursor de célula contendo toda a planilha



createCursorByRange (oExtensao As Object < XSheetCellCursor > )retorna um cursor de célula contendo a extensão de células do parâmetro

O serviço SheetCellCursor fornece toda funcionalidade para operarmos com um cursor de célula.Ele possui as interfaces XSheetCellCursor e XUsedAreaCursor, além de suportar os serviços table.CellCursor e SheetCellRange.

A interface XSheetCellCursor define os métodos a seguir, para contrair ou expandir o cursor:

collapseToCurrentRegion ()collapseToCurrentArray ()collapseToMergedArea ()expandToEntireColumns ()expandToEntireRows ()collapseToSize ( nColunas As Long, nLinhas As Long )

Os métodos abaixo, da interface XUsedAreaCursor, são úteis quando desejamos operar sobre a área utilizada de uma planilha. Por exemplo, identificar a última célula com dados numa planilha.

gotoStartOfUsedArea ( bExpande As Boolean )gotoEndOfUsedArea ( bExpande As Boolean )

A interface XCellCursor, do serviço CellCursor, provê os seguintes métodos, já explicados na seção Tabelas, do capítulo Documentos do Writer:

gotoStart ( )gotoEnd ( )gotoNext ( )gotoPrevious ( )gotoOffSet ( nDeslocColuna As Long, nDeslocLinha As Long )

Para demonstrar o uso de um cursor, digite o código fonte abaixo e execute, observando o resultado.

Sub criaCursorCelulas Dim oDesk As Variant Dim oDoc As Object Dim mProp() As Variant Dim sURL As String ' ' cria documento do Calc oDesk = createUnoService("com.sun.star.frame.Desktop") sUrl = "private:factory/scalc" oDoc = oDesk.LoadComponentFromURL(sUrl, "_blank", 0, mProp()) ' ' trabalha com um cursor Dim oPlan As Object Dim oCursor As Object oPlan = oDoc.getSheets().getByIndex(0)



oCursor = oPlan.createCursorByRange(oPlan.getCellByPosition(0,0)) ' suporta XSpreadSheet MsgBox oCursor.getSpreadsheet().getName() ' edita algumas células ' note que a posição da célula é relativa oCursor.getCellByPosition(0,0).setFormula("Célula A1") oCursor.gotoNext() oCursor.getCellByPosition(0,0).setFormula("Célula B1") oCursor.gotoNext() oCursor.getCellByPosition(0,0).setFormula("Célula C1") ' move o cursor 5 celulas abaixo oCursor.gotoOffSet(0,5) oCursor.getCellByPosition(0,0).setFormula("Abaixo de C1") oCursor.CharHeight = 16 ' obtém toda a área em uso oCursor.gotoStartOfUsedArea(False) oCursor.gotoEndOfUsedArea(True) ' obtem e exibe o endereço do cursor (índices) oEnd = oCursor.getRangeAddress() MsgBox Str$(oEnd.Sheet)+Str$(oEnd.StartColumn)+Str$(oEnd.StartRow) MsgBox Str$(oEnd.Sheet)+Str$(oEnd.EndColumn)+Str$(oEnd.EndRow)End Sub

Aqui, usamos o método createCursorByRange ( ), mas poderíamos ter usado createCursor ( ). Note que, para definir o conteúdo de uma célula, devemos obtê-la chamando o método getCellByPosition ( ), com a posição relativa ao início da extensão de células do cursor. Observe, ainda, como se dá a seleção e identificação da área usada pela planilha.

7.5 Obtendo objetos selecionados

Os principais métodos para obter o conteúdo de uma seleção, estão definidos na interface com.sun.star.frame.XModel, são eles:

getCurrentSelection ( ) As < com.sun.star.uno.XInterface > retorna a seleção no controlador corrente ou Null se não existir um controlador.

getCurrentController ( ) As < com.sun.star.frame.XController > retorna o controlador do modelo ou Null se nenhum controlador foi registrado.

Diversas situações de seleção podem ocorrer, por exemplo: a seleção de uma extensão de células, a seleção de um gráfico, etc. A seguir, vamos apresentar as mais comuns.

O código abaixo define um objeto célula com a primeira célula da extensão selecionada.

' para uma célula: com.sun.star.sheet.SheetCell oCel = ThisComponent.getCurrentSelection().getCellByPosition(0,0)

O trecho de código a seguir obtém uma extensão de células contínuas selecionada e exibe os índices da planilha, coluna inicial e final, linha inicial e final.



' para uma extensão: com.sun.star.sheet.CellRange oExt = oDoc.getCurrentSelection() oEnd = oExt.getRangeAddress() MsgBox Str$(oEnd.Sheet)+Str$(oEnd.StartColumn)+Str$(oEnd.StartRow) MsgBox Str$(oEnd.EndColumn)+Str$(oEnd.EndRow)

Podemos, ainda, obter a seleção de extensões de células não contínuas, numa mesma planilha ou em planilhas diferentes, o bloco de código fonte abaixo lida com esta situação. Num documento do Calc, selecione extensões não contínuas, crie a macro e execute para ver a saída.

Sub selecaoExtensoes Dim oDoc As Object Dim oExts As Object oDoc = ThisComponent ' oExts suporta com.sun.star.sheet.SheetCellRanges oExts = oDoc.getCurrentSelection() MsgBox oExts.getCount() oEnd = oExts.getRangeAddresses() For n=0 To UBound(oEnd) MsgBox Str$(oEnd(n).Sheet)+Str$(oEnd(n).StartColumn)+Str$(oEnd(n).StartRow) Next n MsgBox oExts.getRangeAddressesAsString()End Sub

O método getCurrentSelection ( ) lida com outros objetos, como gráficos ou desenhos. Podemos usar o método getImplementationName ( ) ou supportsService ( ), para tentar uma identificação inicial do objeto selecionado.

Temos, ainda, a interface com.sun.star.view.XSelectionSupplier, que define métodos para seleção pela interface gráfica, entre eles:

select ( oObjeto As Object ) As Booleanse possível, seleciona o objeto oObjeto na interface gráfica.

getSelection ( ) oObjeto As Variant obtém a seleção na interface gráfica, pode retornar um objeto ou uma coleção de objetos.

Estes métodos podem ser chamados através do objeto controlador do modelo, como abaixo:

' seleciona uma extensão de células na planilha ' oDoc = ThisComponent oCtr = oDoc.getCurrentController ( ) oPlan = oDoc.Sheets ( 0 ) oExt = oPlan.getCellRangeByPosition ( 0, 1, 4, 6 ) If ( oCtr.select ( oExt ) ) Then MsgBox "Selecionado na vista" Else MsgBox "Não selecionado"



End If

A API do OpenOffice.org oferece outras funcionalidades, como a seleção de uma extensão de células durante a execução de uma macro, a serem abordadas em outras seções deste documento.

7.6 Formatando

A apresentação final de um trabalho é muito importante e o Calc oferece uma vasta gama de possibilidades para nos auxiliar na formatação dos nossos documentos.

Formatando Parágrafos e Caracteres

Inicialmente, podemos aplicar ao conteúdo de uma célula as técnicas de formatação de parágrafos e caracteres. Os principais serviços, já apresentados no capítulo sobre Documentos do Write, na seção Formatando Texto são:

com.sun.star.style.ParagraphProperties com.sun.star.style.CharacterProperties

O serviço com.sun.star.table.TableRow define as seguintes propriedades para formatação de linhas:

Propriedade DescriçãoHeight Define a altura da linha em 1/100 mm

OptimalHeight Se True, ajusta automaticamente a altura da linha

IsVisible Se True, a linha será exibida

IsStartOfNewPage Se True, insere uma quebra vertical de página nesta linha

O serviço com.sun.star.table.TableColumn define as propriedades abaixo para formatação de colunas:

Propriedade DescriçãoWidth Define a largura da coluna em 1/100 mm

OptimalWidth Se True, ajusta automaticamente a largura da coluna

IsVisible Se True, a coluna será exibida

IsStartOfNewPage Se True, insere uma quebra horizontal de página nesta coluna

Outras propriedades para a formatação de células são cobertas pelos serviços:

com.sun.star.table.CellProperties



com.sun.star.table.TableBorder com.sun.star.table.BorderLineO serviço CellProperties contém diversas propriedades. As mais importantes foram apresentadas no capítulo Documentos do Writer, na seção sobre Tabelas.

Vamos aplicar alguma formatação ao exemplo criado pela Sub editaPlanilha. Adicione o código fonte abaixo no final da sub-rotina, execute e observe a saída:

' Formatação Dim oExtensao As Object Dim oLinha As Object Dim oColuna As Object ' ' formata parágrafos e caracteres oExtensao = oPlanilha.getCellRangeByPosition(0, 0, 5, 0) oExtensao.CharHeight = 12 oExtensao.CharWeight = com.sun.star.awt.FontWeight.BOLD oExtensao.ParaAdjust = com.sun.star.style.ParagraphAdjust.CENTER ' ajusta a altura da linha 1 oLinha = oPlanilha.getRows().getByIndex(0) oLinha.OptimalHeight = True ' ajusta a largura da coluna B oColuna = oPlanilha.getColumns().getByIndex(1) oColuna.OptimalWidth = True

A destacar, o método de recuperação de linhas e colunas, via acesso indexado.

Mesclando Células

Numa planilha, podemos mesclar células, a interface com.sun.star.util.XMergeable define os métodos abaixo, com esta finalidade:

merge ( bMerge As Boolean )Se bMerge é True mescla a área do objeto, senão separa.

getIsMerged ( ) As BooleanRetorna True se a área do objeto estiver mesclada, senão retorna False

Inserindo Bordas

Outro aspecto importante na apresentação de uma planilha é a colocação de bordas em torno das células. O serviço CellProperties contém as seguintes propriedades, que definem o tipo de borda de uma célula ou extensão de células:

Popriedade DescriçãoTableBorder Define a borda de uma célula ou extensão de células

TopBorder Define a borda superior de cada célula da extensão

BottomBorder Define a borda inferior de cada célula da extensão

RightBorder Define a borda direita de cada célula da extensão



LeftBorder Define a borda esquerda de cada célula da extensão

O principal elemento de cada uma destas propriedades é a estrutura BorderLine, contendo, dentre outros, os campos Color e OuterLineWidth para a cor e a espessura da linha. Para a propriedade TableBorder, podemos definir quatro linhas: TopLine, BottomLine, RightLine e LeftLine.

Prosseguindo com o nosso exemplo, vamos mesclar algumas células e, depois, definir bordas para a nossa planilha. Acrescente o código fonte a seguir na sub-rotina Sub editaPlanilha e observe o resultado da execução:

' mescla células oExtensao = oPlanilha.getCellRangeByPosition(0, 7, 3, 7) oExtensao.merge(True) ' Define Borda Dim oBorda As New com.sun.star.table.TableBorder Dim oLinBorda As New com.sun.star.table.BorderLine ' oExtensao = oPlanilha.getCellRangeByPosition(0, 0, 4, 7) ' define a espessura e a cor da linha da borda oLinBorda.OuterLineWidth = 30 oLinBorda.Color = CLng( "&H000099" ) oExtensao.setPropertyValue("TopBorder", oLinBorda) oExtensao.setPropertyValue("RightBorder", oLinBorda) oExtensao.setPropertyValue("LeftBorder", oLinBorda) oExtensao.setPropertyValue("BottomBorder", oLinBorda) ' define e aplica uma TableBorder oLinBorda.OuterLineWidth = 100 oLinBorda.Color = CLng( "&HAABBCC" ) oBorda.TopLine = oLinBorda oBorda.BottomLine = oLinBorda oBorda.RightLine = oLinBorda oBorda.LeftLine = oLinBorda oBorda.IsTopLineValid = True oBorda.IsBottomLineValid = True oBorda.IsRightLineValid = True oBorda.IsLeftLineValid = True oExtensao.setPropertyValue("TableBorder", oBorda)

Inicialmente definimos as bordas de todas as células de oExtensao, depois aplicamos uma borda na extensão. Note os campos Is...Valid definidos como True.

Formatação Numérica

O OpenOffice.org possui diversas categorias de formatação numérica. Cada categoria possui vários formatos pré-definidos. Através da interface com.sun.star.util.XNumberFormatsSupplier podemos ler, modificar e adicionar novos formatos aos nossos documentos.

A interface XNumberFormatsSupplier contém os métodos abaixo:

getNumberFormats ( ) As Object < com.sun.star.util.XNumberFormats >



getNumberFormatsSettings ( ) As Object < com.sun.star.beans.XPropertySet >

Entre os métodos da interface XNumberFormats, temos:

getByKey (nChave As Long) As Object < XPropertySet >queryKeys (nCategoria As Long, nLocal As Long, bInserir As Boolean) As aVetor ( )queryKey (sFormato As String, nLocal As Long, bProcura As Boolean) As LongaddNew ( sFormato As String, nLocal As Long ) As Long

A interface com.sun.star.util.XNumberFormatTypes contém métodos para obter o índice de alguns formatos pré-definidos. Aqui, usaremos o método:

getStandardFormat (nTipo AS Long, nLocal As Long) As Long

O grupo de constantes com.sun.star.util.NumberFormat define valores para, dentre outras, as seguintes categorias: DATE, TIME, CURRENCY, NUMBER, DATETIME.

O serviço CellProperties contém a propriedade NumberFormat, que define o tipo formatação numérica de uma célula ou extensão de células.

Vejamos um exemplo ilustrativo. Num documento do Calc, crie a macro abaixo, execute-a e observe o resultado.

Sub exibeFormatosNumericos Dim oDoc As Object Dim oFormatos As Object Dim mChaves As Variant Dim mProp As Variant Dim oLocal As New com.sun.star.lang.Locale oDoc = ThisComponent oFormatos = oDoc.getNumberFormats() oSettings = oDoc.getNumberFormatSettings() oInfo = oSettings.getPropertySetInfo() oProp = oInfo.getProperties() MsgBox UBound(oProp) For n = 0 To UBound(oProp) MsgBox oProp(n).Name Next n mChaves = oFormatos.queryKeys (0, oLocal, FALSE) MsgBox UBound(mChaves) mProp = oFormatos.getByKey(11).getPropertyValues() ' obtem os nomes das propriedades sMsg = "" For n=0 To UBound(mProp) sMsg = sMsg + mProp(n).Name + Chr$(13) Next n MsgBox sMsg ' exibe o valor de FormatString MsgBox mProp(0).Value

End Sub



Agora, vamos retornar à nossa sub-rotina Sub editaPlanilha para aplicar formatação numérica em algumas células. Adicione o código abaixo, execute e observe a saída:

' Formatos Numéricos Dim oFormatos As Object Dim aLocal() As New com.sun.star.lang.Locale ' obtem os formatos numericos do modelo oFormatos = oDoc.getNumberFormats() ' obtém o índice do formato padrão para MOEDA n%=oFormatos.getStandardFormat(com.sun.star.util.NumberFormat.CURRENCY,aLocal()) ' obtem uma extensão de células oExtensao = oDoc.getSheets().getByIndex(0).getCellRangeByPosition(3,1,4,6) ' altera o formato padrão para MOEDA oExtensao.NumberFormat = n% ' obtém uma célula e altera para MOEDA oCelula = oPlanilha.getCellByPosition(4, 7) oCelula.NumberFormat = n%

Note a declaração dos objetos, o uso do método getStandardFormat () e o uso da propriedade NumberFormat para alterar a formatação das células.

Formatação Condicional

O serviço com.sun.star.sheet.SheetCellRange contém as seguintes propriedades para formatação condicional:

conditionalFormat - define condições para formatação condicionalconditionalFormatLocal - define condições locais para formatação condicional

A interface XSheetConditionalEntries provê os métodos a seguir para operações com as condições de formatação:

addNew ( mCond () As < com.sun.star.beans.PropertyValue > )o parâmetro mCond é um vetor com as seguintes entradas:

- “Operator” com os possíveis valores, definidos em com.sun.star.sheet.ConditionOperator

NONE, EQUAL, NOT_EQUAL, GREATER, GREATER_EQUAL,

LESS, LESS_EQUAL, BETWEEN, NOT_BETWEEN, FORMULA

- “Formula1” contendo uma cadeia com um valor ou fórmula

- “Formula2” contendo um valor ou fórmula, usada quando o operador for BETWEEN

- “StyleName” contendo um nome de estilo de formatação de célula

removeByIndex ( nIndice As Long )remove a condição nIndice

clear ( )limpa as condições atuais de formatação

Acrescente o código abaixo no final da Sub editaPlanilha, execute e observe a saída:



' FORMATAÇÃO CONDICIONAL ' Dim mCond (2) As New com.sun.star.beans.PropertyValue Dim oEntradas As Variant ' obtem uma extensão de células oExtensao = oDoc.getSheets().getByIndex(0).getCellRangeByPosition(4,1,4,6) ' obtém a formatação condicional corrente oEntradas = oExtensao.getPropertyValue("ConditionalFormat") ' define as propriedades de uma condição para formatação mCond(0).Name = "Operator" mCond(0).Value = com.sun.star.sheet.ConditionOperator.GREATER mCond(1).Name = "Formula1" mCond(1).Value = "500" mCond(2).Name = "StyleName" mCond(2).Value = "Result" ' limpa as condiçoes existentes oEntradas.clear() ' adiciona a nova condição oEntradas.addNew(mCond()) ' aplica a formatação condicional oExtensao.setPropertyValue("ConditionalFormat", oEntradas)

Neste código, aplicamos o estilo “Resultado” se o valor da célula for maior que R$ 500,00.

Podemos, também, aplicar estilos de formatação de células definidos pelos usuários.

7.7 Busca e Substituição

A busca e substituição, num documento do Calc, funciona de modo semelhante àquele já demonstrado na seção Busca e Substituição, do capítulo Documentos do Writer.

Relembrando, a interface com.sun.star.util.XSearchable provê os métodos abaixo para busca:

createSearchDescriptor ( ) As Object <SearchDescriptor>FindAll ( oDescritor As Object ) As Object <com.sun.star.container.XIndexAccess>FindFirst ( oDescritor As Object ) As Object <com.sun.star.uno.XInterface>FindNext ( oInicio As Object, oDescritor As Object ) As Object <Xinterface>

O serviço SearchDescriptor tem os métodos abaixo:

getSearchString ( ) As StringsetSearchString ( sCadeia As String )

Eis algumas de suas propriedades:

Propriedade DescriçãoSearchBackwards Se True, busca para o início do documento

SearchCaseSensitive Se True, considera maiúsculas / minúsculas



Propriedade DescriçãoSearchWords Se True, localiza apenas as células com o texto e nada

mais, senão localiza também as células onde o texto é parte do conteúdo.

SearchStyles Se True, busca por um estilo de célula

Vejamos um exemplo de busca: crie um novo documento do Calc, preencha algumas células com o texto “TOTAL” e “TOTAL GERAL”, em seguida crie a macro abaixo e execute.

Sub buscaTexto Dim oDoc As Object Dim oDescBusca As Object Dim oPlanilha As Object oDoc = ThisComponent oPlanilha = oDoc.Sheets(0) oDescBusca = oPlanilha.createSearchDescriptor() oDescBusca.SearchWords = True oDescBusca.setSearchString ("TOTAL") oResultado = oPlanilha.findFirst( oDescBusca ) i = 0 Do Until IsNull(oResultado) oResultado.CharColor = RGB(250,100,50) oResultado = oPlanilha.findNext(oResultado, oDescBusca ) i = i + 1 Loop MsgBox "Ocorrências de "+oDescBusca.getSearchString() + " " + Str$(i)End Sub

Agora, altere a propriedade SearchWords para False e execute novamente a macro observando o seu resultado.

A substituição de texto é implementada pela interface XReplaceable, que herda as características de XSearchable. Ela provê os métodos:

createReplaceDescriptor ( ) As Object <com.sun.star.util.XReplaceDescriptor>replaceAll ( xDescritor As Object <com.sun.star.util.XReplaceDescriptor>) As Long

O serviço ReplaceDescriptor tem métodos para as propriedades da cadeia:

getReplaceString ( ) As StringsetReplaceString ( sCadeia As String )

Eis uma busca e substituição simples, no mesmo documento do exemplo acima:

Sub substituiTexto Dim oDoc As Object Dim oDescritor As Object Dim oPlanilha As Object



oDoc = ThisComponent oPlanilha = oDoc.Sheets(0) oDescritor = oPlanilha.createReplaceDescriptor() oDescritor.setSearchString( "TOTAL GERAL" ) oDescritor.setReplaceString( "Total" ) n = oPlanilha.replaceAll(oDescritor) sMsg = oDescritor.getSearchString()+“ por “+oDescritor.getReplaceString() MsgBox sMsg + “ = “ + Str$(n)End Sub

Note que devemos executar a busca e a substituição numa extensão de células. Nos exemplos, utilizamos toda a planilha.

7.8 Ordenando

Para a ordenação de uma extensão de células, devemos utilizar os mesmos conceitos e serviços já apresentados na seção Tabelas, do capítulo sobre Documentos do Writer.

Seguem, abaixo, os principais métodos e propriedades utilizados nesta tarefa.

Métodos da interface com.sun.star.util.XSortable:

createSortDescriptor ( ) As Variant <com.sun.star.beans.PropertyValue> sort (xDescritor As Variant <com.sun.star.beans.PropertyValue> )

Algumas das propriedades do descritor de ordenação (SortDescriptor):

Propriedade DescriçãoIsCaseSensitive Se True, considera maiúsculas / minúsculas

SortAscending Define a ordem da ordenação

SortColumns Se True ordena as colunas, senão ordena as linhas.

O serviço com.sun.star.table.TableSortDescriptor inclui o serviço SortDescriptor e possui as propriedades abaixo:

Propriedade DescriçãoSortFields Descreve os campos de ordenação

<com.sun.star.util.SortField>

MaxFieldCount Define o número máximo de campos, somente leitura

Orientation Define a orientação da ordenação <com.sun.star.table.TableOrientation>

ContainsHeader Se True, não ordena a primeira linha ou coluna



No próximo bloco de código, veremos a ordenação de uma extensão de células (A2:E7), do documento criado pela Sub editaPlanilha. Digite o código abaixo no final da macro, execute e observe a saida.

' ================================= ' ORDENANDO UMA EXTENSÃO DE CÉLULAS ' ================================= Dim oCampoOrd(0) As New com.sun.star.util.SortField Dim oDescrOrd As Variant ' ' define a extensão a ser ordenada (A2:E7) oExtensao = oDoc.getSheets().getByIndex(0).getCellRangeByPosition(0,1,4,6) ' define o campo de ordenação e suas propriedades oCampoOrd(0).Field = 0 oCampoOrd(0).SortAscending = True oCampoOrd(0).FieldType = com.sun.star.util.SortFieldType.ALPHANUMERIC ' cria o descritor de ordenação oDescrOrd = oExtensao.createSortDescriptor() ' define as propriedades do descritor oDescrOrd(0).Name = "SortFields" oDescrOrd(0).Value = oCampoOrd() oDescrOrd(1).Name = "ContainsHeader" oDescrOrd(1).Value = False oDescrOrd(2).Name = "SortColumns" oDescrOrd(2).Value = False ' ordena a extensão oExtensao.sort(oDescrOrd())

Note que iniciamos com a declaração das variáveis, criamos uma extensão de células com uma chamada ao método getCellRangeByPosition (), definimos as propriedades do campo de ordenação, criamos o descritor e definimos as suas propriedades (o campo de ordenação é uma propriedade do descritor) e, finalmente, invocamos o método sort () para executar a sua tarefa.

7.9 Filtrando dados

Nesta seção, veremos os principais serviços e interfaces relacionados com a aplicação de filtros numa extensão de células.

A interface com.sun.star.sheet.XSheetFilterable define os seguintes métodos:

createFilterDescriptor ( bVazio As Boolean ) As Object < XSheetFilterDescriptor >cria um descritor vazio se bVazio for True, senão preserva as informações

filter ( oDescritor As Object < XSheetFilterDescriptor > )aplica o filtro na extensão de células

O serviço SheetFilterDescriptor controla as condições da operação de filtragem. Eis algumas de suas propriedades:

IsCaseSensitive - se True, destingue maiúsculas e minúsculasSkipDuplicates - seTrue, as entradas duplicadas serão excluídas



Orientation - filtra por Linhas ou Colunas ( TableOrientation )ContainsHeader - a primeira linha ou coluna é um cabeçalhoCopyOutputData - se True, o resultado será copiado para outro local OutputPosition - local da cópia ( estrutura CellAddress )

A interface XSheetFilterDescriptor contém os métodos abaixo para obter e definir os campos com os critérios do filtro:

getFilterFields ( ) aCampos () As Object < TableFilterField >retorna os campos com os critérios do filtro

setFilterFields ( aCampos () As Object < TableFilterField > )define os campos com os critérios do filtro

A estrutura com.sun.star.table.TableFilterField contém os elementos a seguir:

Connection - como será a conexão com a condição anterior ( Or / And )Field - a coluna usada na condiçãoOperator - operador condicional ( FilterOperator )IsNumeric - se True, o valor do campo (Field) é numérico NumericValue - valor do campo, usar se IsNumeric for TrueStringValue - cadeia de caracteres, usar se IsNumeric for False

Os passos necessários para filtrar dados numa planilha são:

a) obter a extensão de células a ser filtrada;

b) definir a estrutura dos campos com os critérios do filtro;

c) criar e definir os dados do descritor do filtro;

d) aplicar o filtro.

Vejamos um trecho de código fonte que aplica um filtro simples numa extensão de células.

Sub aplicaFiltro Dim oDoc As Object Dim oPlan As Object Dim oExt As Object Dim oDescFiltro As Variant Dim oCamposFiltro(0) As New com.sun.star.sheet.TableFilterField oDoc = ThisComponent oPlan = oDoc.getSheets().getByIndex(0) oExt = oPlan.getCellRangeByPosition(0,1,4,6) ' define a estrutura TableFilterField oCamposFiltro(0).Field = 4 oCamposFiltro(0).IsNumeric = True oCamposFiltro(0).Operator = com.sun.star.sheet.FilterOperator.GREATER_EQUAL oCamposFiltro(0).NumericValue = 300 ' cria o descritor do filtro vazio (True) oDescFiltro = oExt.createFilterDescriptor (True) ' define o campo de filtro oDescFiltro.setFilterFields (oCamposFiltro())



' aplica o filtro oExt.filter (oDescFiltro) ' MsgBox "OK para filtrar Caracteres" ' redefine a estrutura TableFilterField oCamposFiltro(0).Field = 0 oCamposFiltro(0).IsNumeric = False oCamposFiltro(0).Operator = com.sun.star.sheet.FilterOperator.GREATER oCamposFiltro(0).StringValue = "A 1" ' cria um descritor de filtro vazio (True) oDescFiltro = oExt.createFilterDescriptor (True) ' define o campo de filtro oDescFiltro.setFilterFields (oCamposFiltro()) ' aplica o filtro oExt.filter (oDescFiltro)End Sub

Se você quiser experimentar este código, crie uma macro no documento gerado pela Sub editaPlanilha e execute, observando a saída. Note que a estrutura TableFilterField pode ter mais de um campo com critérios de filtragem.

Tente acrescentar código para copiar o resultado do filtro na Planilha2 do documento.

7.10 Inserindo Subtotais

Operações de subtotais, sobre numa extensão de células, são de grande praticidade. A API do OpenOffice.org oferece diversos serviços e interfaces para a programação de subtotais.

A interface XSubTotalCalculatable define os métodos abaixo:

createSubTotalDescriptor ( bVazio As Boolean ) As Object < XSubTotalDescriptor >cria um descritor de subtotal vazio se bVazio for True, senão preserva dados anteriores

applySubTotals ( oDesc As Object < XSubTotalDescriptor >, bSubstitui As Boolean )aplica o subtotal, se bSubstitui for True o resultado anterior será substituído

removeSubTotals ( )remove os subtotais do objeto

O serviço SubTotalDescriptor é uma representação de como os subtotais serão criados. A seguir, algumas de suas propriedades:

InsertPageBreaks - insere quebra de página após cada subtotalIsCaseSensitive - considera letras maiúsculas / minúsculasEnableUserSortList - se True permite a definição de uma lista para ordenaçãoUserSortListIndex - a lista para ordenação, se EnableUserSortList for TrueEnableSort - define se o conteúdo dos campos serão ordenadosSortAscending - se True ordenação crescente (depende de EnableSort )

Além das propriedades acima, o descritor deve conter os campos de subtotais. A interface XSubTotalDescriptor provê métodos para adicionar ou limpar campos:

addNew ( aColunas() As < SubTotalColumn >, nColGrupo As Long)



adiciona os campos ao descritor, nColGrupo especifica a coluna base para agrupamento

clear ( )remove todos os campos de subtotais do objeto

A estrutura com.sun.star.sheet.SubTotalColumn contém os elementos:

Column - índice da coluna a subtotalizarFunction - o tipo de subtotal, definido em com.sun.star.sheet.GeneralFunction

Os passos necessários para adicionar linhas com subtotais numa extensão de células são:

a) obter a extensão de células a ser subtotalizada;

b) definir a estrutura dos campos de subtotal;

c) criar e definir os dados do descritor de subtotal;

d) aplicar a operação de subtotal.

Vejamos um trecho de código fonte que aplica um subtotal numa extensão de células.

Sub aplicaSubTotal Dim oDoc As Object Dim oPlan As Object Dim oExt As Object Dim oDescSubTotal As Variant Dim oCamposSubTotal(0) As New com.sun.star.sheet.SubTotalColumn oDoc = ThisComponent oPlan = oDoc.getSheets().getByIndex(0) oExt = oPlan.getCellRangeByPosition(0,0,4,6) ' define a estrutura SubTotalColumn oCamposSubTotal(0).Column = 4 oCamposSubTotal(0).Function = com.sun.star.sheet.GeneralFunction.SUM ' cria o descritor do subtotal oDescSubTotal = oExt.createSubTotalDescriptor (True) ' adiciona o campo subtotal e a coluna base oDescSubTotal.addNew (oCamposSubTotal(), 0) ' aplica o subtotal oExt.applySubTotals(oDescSubTotal, True)End Sub

Se você quiser experimentar este código, crie uma macro no documento gerado pela Sub editaPlanilha, execute e analise o resultado.

7.11 Gráficos

Um gráfico é um documento embutido num outro documento do OpenOffice.org. A API do OpenOffice.org contém diversos serviços e interfaces para a geração de gráficos, a partir dos dados contidos numa planilha.

O serviço com.sun.star.table.TableCharts suporta os métodos das interfaces XTableCharts, XIndexAccess e XEnumerationAccess.



Métodos da interface com.sun.star.table.XTableCharts:

addNewByName ( sNome As String, oArea As Object < com.sun.star.awt.Rectangle >, oExt ( ) As Object < com.sun.star.table.CellRangeAddress >, bTitCol As Boolean, bTitLin As Boolean ) Adiciona o gráfico na coleção de gráficos da planilha. Os seus parâmetros são:

sNome - o nome do gráfico oArea - a área (retângulo) aonde o gráfico será plotadooExt - a extensão de células com os dadosbTitCol - se True, os dados da linha superior serão usados na legenda do gráficobTitLin - se True, os dados da primeira coluna serão usados como títulos no eixo

removeByName ( sNome As String ) remove o gráfico com o nome sNome da coleção.

O serviço com.sun.star.table.TableChart suporta a interface XTableChart com os métodos:

getHasColumnHeaders ( ) As BooleansetHasColumnHeaders ( bTituloColuna As Boolean ) getHasRowHeaders ( ) As BooleansetHasRowHeaders ( bTituloColuna As Boolean ) getRanges ( ) As sExtensoes ( ) < CellRangeAddress > setRanges ( sExtensoes ( ) As Object < CellRangeAddress > )

Um documento gráfico contém uma referência para uma fonte de dados, um diagrama e algumas propriedades como título, sub-título e legenda. O serviço ChartDocument é o modelo do documento gráfico e suporta as interfaces XChartDocument, XPropertySet e XMultiServiceFactory . Ele possui as seguintes propriedades:

HasMainTitle - Se True, exibe o título principalHasSubTitle - Se True, exibe o subtítulo HasLegend - Se True, exibe a legenda

A interface com.sun.star.chart.XChartDocument provê os métodos:

getTitle ( ) As < com.sun.star.drawing.XShape > getSubTitle ( ) As < com.sun.star.drawing.XShape > getLegend ( ) As < com.sun.star.drawing.XShape > getArea ( ) As < com.sun.star.beans.XPropertySet > getDiagram ( ) As < com.sun.star.chart.XDiagram > setDiagram ( oDiagrama As < com.sun.star.chart.XDiagram >)getData ( ) As < com.sun.star.chart.XChartData >attachData ( oDadosExternos As < com.sun.star.chart.XChartData >)

O diagrama é o objeto que contém a forma do gráfico, baseada no serviço Diagram e suas interfaces XDiagram e XPropertySet. Diferentes tipos de diagramas podem ser criados com o método createInstance (), da interface XMultiServiceFactory. Eis alguns serviços para tipos de diagramas:



com.sun.star.chart.BarDiagram com.sun.star.chart.LineDiagram com.sun.star.chart.PieDiagram com.sun.star.chart.AreaDiagram com.sun.star.chart.XYDiagram

Podemos alterar a propriedade Diagram de um gráfico com o código a seguir:

oDiagrama = oGraf.createInstance("com.sun.star.chart.PieDiagram") oGraf.setDiagram ( oDiagrama )

O serviço com.sun.star.chart.Diagram tem as propriedades abaixo:

DataRowSource - define se a série de dados é por linhas ou colunasDataCaption - define como a legenda dos dados será exibida

Para criar um gráfico devemos seguir os passos abaixo:

a) definir os dados a serem exibidos no gráfico;

b) definir a área retangular aonde o gráfico será desenhado;

c) adicionar o gráfico à coleção;

d) recuperar o objeto gráfico embutido.

e) definir as propriedades do gráfico.

Vejamos um exemplo simples. Digite a macro a seguir e execute para ver a saída:

Sub criaGrafico Dim oDesk As Variant Dim oDoc As Object Dim mProp() As Variant Dim sURL As String ' cria documento do Calc oDesk = createUnoService("com.sun.star.frame.Desktop") sUrl = "private:factory/scalc" oDoc = oDesk.LoadComponentFromURL(sUrl, "_blank", 0, mProp()) ' edita células da planilha Dim oPlanilha As Object Dim oCelula As Object Dim sTitCol() As String ' escreve os titulos das colunas sTitCol = Array ("Período","Computador","Periférico","Serviço","Total") oPlanilha = oDoc.getSheets().getByIndex(0) For i% = 0 To 4 oCelula = oPlanilha.getCellByPosition(i%, 0) oCelula.setString(sTitCol(i%)) Next i% ' preenche as células com texto, valor e formula For i% = 1 To 4 For j% = 0 To 4 oCelula = oPlanilha.getCellByPosition(j%, i%) If (j% = 0) Then


http://com.sun.star.chart.PieDiagram/


oCelula.setString(Str$(i%) + "º Trim") ElseIf (j% > 0 And j < 4) Then oCelula.setValue(1000 * Rnd()) Else sExt = "B" + Trim$(Str$(i%+1)) + ":" + "D" + Trim$(Str$(i%+1)) sFormula = "=Soma(" + sExt + ")" oCelula.FormulaLocal = sFormula End If Next j% Next i% ' ' insere um gráfico de colunas Dim oRet As New com.sun.star.awt.Rectangle Dim oEndExt(0) As New com.sun.star.table.CellRangeAddress Dim oGraficos As Object ' define o nome do gráfico sNome = "Trimestral" ' define o endereço da extensão de células com os dados oEndExt(0).Sheet = 0 oEndExt(0).StartColumn = 0 oEndExt(0).StartRow = 0 oEndExt(0).EndColumn = 3 oEndExt(0).EndRow = 4 ' define a área do gráfico oRet.X = 1000 oRet.Y = 3000 oRet.Width = 12000 oRet.Height = 12000 ' obtém a coleção de gráficos da Planilha1 oGraficos = oPlanilha.Charts ' adiciona um gráfico à coleção oGraficos.addNewByName(sNome, oRet, oEndExt(), True, True) ' define as propriedades(Titulo) oGraf = oGraficos.getByName(sNome).getEmbeddedObject() oGraf.Title.String = "Faturamento Trimestral" oGraf.HasSubTitle = True oGraf.SubTitle.String = "Ano 2003"End Sub

Começamos preenchendo as células com os dados, depois, definimos o nome do gráfico, a extensão de células com os dados e a área (retângulo) aonde o gráfico será plotado. Após estes passos preliminares, obtemos a coleção dos gráficos da planilha e adicionamos o nosso gráfico na coleção, com uma chamada ao método addNewByName ( ). Finalmente, obtemos o objeto gráfico embutido, com uma chamada ao método getByName ( ) associada ao método getEmbeddedObject ( ) e, então, alteramos algumas propriedades do gráfico.

Aproveitando o exemplo acima, vamos mostrar como alterar a propriedade Diagram de um gráfico. Acrescente o código fonte abaixo ao final da Sub criaGrafico e execute para criar um gráfico do tipo Pizza, representando os dados da linha 2 da planilha.

' Criando um gráfico do tipo Pizza Dim oExtPizza(1) As New com.sun.star.table.CellRangeAddress ' MsgBox "OK para uma Pizza"



' remove o gráfico de barras oGraficos.removeByName(sNome) sNome = "GrafPizza" ' define o endereço da extensão de células com legendas oExtPizza(0).Sheet = 0 oExtPizza(0).StartColumn = 0 oExtPizza(0).StartRow = 0 oExtPizza(0).EndColumn = 3 oExtPizza(0).EndRow = 0 ' define o endereço da extensão de células com dados oExtPizza(1).Sheet = 0 oExtPizza(1).StartColumn = 0 oExtPizza(1).StartRow = 1 oExtPizza(1).EndColumn = 3 oExtPizza(1).EndRow = 1 ' adiciona um gráfico à coleção oGraficos.addNewByName(sNome, oRet, oExtPizza(), True, True) ' define as propriedades oGraf = oGraficos.getByName(sNome).getEmbeddedObject() oGraf.Diagram = oGraf.createInstance("com.sun.star.chart.PieDiagram") oGraf.Diagram.DataRowSource = com.sun.star.chart.ChartDataRowSource.ROWS oGraf.Title.String = "1º Trimestre – 2003"

Observe que temos um vetor de estruturas CellRangeAddress, onde o primeiro elemento contém os dados da legenda do gráfico e o segundo os dados a serem representados. Note também a mudança da propriedade Diagram com uma chamada ao método createInstance ( ) e a mudança da propriedade DataRowSource do diagrama.

Note, ainda, que o fato de podermos definir um vetor CellRangeAddress, indica que podemos ter extensões de células, consecutivas ou não, contendo os dados a serem representados graficamente.

7.12 Seleção durante a execução da macro

A API do OpenOffice.org oferece um mecanismo simples para a seleção de uma extensão de células, durante a execução da macro. Segue uma descrição dos principais serviços e interfaces utilizados nesta tarefa.

O serviço com.sun.star.sheet.RangeSelectionArguments define as propriedades abaixo:

InitialValue Valor inicial para a seleção, por ex: $Planilha1.$a$1:$b$5Title Título do diálogo da seleção CloseOnMouseRelease Se True encerra a seleção após a liberação do botão do mouse

A interface com.sun.star.sheet.XRangeSelection provê os seguintes métodos:

startRangeSelection ( aProp () As Object < com.sun.star.beans.PropertyValue > ) inicia o processo de seleção da extensão de células

abortRangeSelection ( )



aborta o processo de seleção

addRangeSelectionListener( oList As < com.sun.star.sheet.XRangeSelectionListener>) adiciona um “listener” para monitorar o término ou o cancelamento da seleção

removeRangeSelectionListener( oList As < com.sun.star.sheet.XRangeSelectionListener>) remove o “listener” especificado no parâmetro

addRangeSelectionChangeListener( oList As < XRangeSelectionChangeListener >) adiciona um “listener” para monitorar mudanças durante a seleção

removeRangeSelectionChangeListener ( oList As < XRangeSelectionChangeListener >) remove o “listener” de mudanças especificado no parâmetro

A interface com.sun.star.sheet.XRangeSelectionListener especifica os métodos abaixo, a serem definidos pelo usuário, usando o Basic:

done ( aEvento As < com.sun.star.sheet.RangeSelectionEvent > ) contém o código a ser executado após o término da seleção

aborted ( aEvento As < com.sun.star.sheet.RangeSelectionEvent > ) contém o código a ser executado após o cancelamento da seleção

A estrutura com.sun.star.sheet.RangeSelectionEvent contém o elemento RangeDescriptor, que é uma representação textual da extensão de células selecionadas.

Devemos criar uma instância do “listener” chamando a função createUnoService ( ) do OpenOffice.org Basic, eis a sua sintaxe:

createUnoService ( sPrefixo As String, sListener As String ) As Object sPrefixo: é o prefixo usado no nome dos métodos do listener. O caractere sublinhado deve ser o último do prefixo ( ex: “listen_” ). sListener: é o nome da interface do listener retorna um objeto “listener”, cujos métodos podem ser usados na macro.

Bem, já temos todas as ferramentas necessárias para executar a nossa tarefa. Vejamos como usá-las através de um exemplo simples de seleção.

Abra uma nova planilha e salve-a, em seguida crie um novo módulo para a macro, isto porque usamos variáveis Públicas em nossa macro. Finalmente, digite o código fonte abaixo (ou copie e cole) no novo módulo. Ative a planilha e execute a macro, surge uma caixa de diálogo solicitando a seleção da extensão, use o mouse ou o teclado para selecionar. Após a seleção, a propriedade CharHeight da extensão será alterada.

'' seleção de uma extensão durante a execução da macro' usando XRangeSelectionListener'Public aListener As Object Public aResult As StringPublic bSelecao As Boolean

Sub Main' Dim oDoc As Object Dim oDocView As Object



Dim oPlan As Object Dim aProp(2) As New com.sun.star.beans.PropertyValue ' oDoc = ThisComponent oDocView = oDoc.getCurrentController() ' define um ouvinte (listener) Set aListener = CreateUnoListener("oList_", _ "com.sun.star.sheet.XRangeSelectionListener") ' adiciona o ouvinte oDocView.addRangeSelectionListener ( aListener ) ' define as propriedades para a seleção aProp(0).Name = "InitialValue" aProp(0).Value = "" '"$Planilha1.$A$1:$B$2" aProp(1).Name = "Title" aProp(1).Value = "Selecione a " aProp(2).Name = "CloseOnMouseRelease" aProp(2).Value = True ' inicia o processo de seleção bSelecao = False oDocView.startRangeSelection ( aProp () ) Do While ( bSelecao = False) ' aguarda a seleção Loop ' remove o ouvinte (listener) oDocView.removeRangeSelectionListener(aListener) ' opera sobre o resultado da seleção If ( bSelecao = True And Len (aResult) > 0 ) Then MsgBox aResult oPlan = oDocView.getActiveSheet() oRange = oPlan.getCellRangeByName(aResult) oRange.CharHeight = 20 Else MsgBox "Seleção recusada" End If'End Sub

' Métodos da interface com.sun.star.sheet.XRangeSelectionListener ' done ( )Sub oList_done ( oEvent ) ' obtem o nome da extensão aResult = oEvent.RangeDescriptor bSelecao = TrueEnd Sub

' aborted ( )Sub oList_aborted ( oEvent ) bSelecao = TrueEnd Sub

Sub oList_disposing () ' implementação mínimaEnd Sub



Inicialmente definimos algumas variáveis públicas, depois obtemos a vista do documento, pois a seleção ocorre na vista e chamamos a função createUnoListener para criar uma instância da interface XRangeSelectionListener, note o prefixo com o sublinhado no final.

Após a criação, registramos o “listener” com addRangeSelectionListener, é como se estivessemos dizendo ao OpenOffice.org: “ei, temos um novo monitor de seleção para a vista deste documento”.

Definimos então, as propriedades iniciais para a nossa seleção, note que o valor da propriedade CloseOnMouseRelease é True, e atribuimos o valor False para o sinalizador bSelecao. Depois, chamamos o método startRangeSelection passando o vetor com as propriedades iniciais.

A seguir, no laço Do While ... Loop, aguardamos a seleção do usuário. A macro só abandona o laço quando o valor de bSelecao for True. Isto só acontece nos métodos done () e aborted () do “listener”. Estes métodos são chamados automaticamente pelo OpenOffice.org no final ou no cancelamento da seleção, isto é, quando o usuário completar a seleção, liberando o botão do mouse ou quando ele fechar o diálogo de seleção.

Terminada a seleção, removemos o “listener” com o método removeRangeSelectionListener e, finalmente, processamos o resultado da nossa seleção.

Além da sub-rotina Main, temos, em nossa macro, as sub-rotinas abaixo:

Sub oList_done ( oEvent ) - corresponde ao método done ( ) da interfaceSub oList_aborted ( oEvent ) - corresponde ao método aborted ( ) da interfaceSub oList_disposing ( ) - chamada na remoção do “listener”

Na sub-rotina done ( ), atribuimos a descrição textual da seleção à variável pública aResult, através do elemento RangeDescriptor da estrutura oEvent, e, depois, definimos o nosso sinalizador bSelecao para True.

Na sub-rotina aborted ( ), apenas definimos o nosso sinalizador bSelecao para True.

Note o uso do prefixo de createUnoListener antecedendo os nomes dos métodos da interface.

A API do OpenOffice.org contém muitas interfaces que usam “listeners”. É muito importante que todos os métodos da interface sejam implementados com o Basic. Quando nenhuma ação for necessária, faça uma implementação mínima, como em oList_disposing ( ).

7.13 Movimentando dados

Podemos inserir, copiar, mover ou remover um grupo de células, no documento, através da interface com.sun.star.sheet.XCellRangeMovement, do serviço Spreadsheet, e seus métodos:

insertCells ( mEndereco As < com.sun.star.table.CellRangeAddress >, nModo As Integer)insere as células no local mEndereco; os valores de nModo estão definidos na enumeração <com.sun.star.sheet.CellInsertMode >:

NONE - nenhuma célula será movidaDOWN - as células abaixo das células inseridas são movidas para baixoRIGHT - as células à direita das células inseridas são movidas para a direita



ROWS - as linhas abaixo das células inseridas são movidas para baixoCOLUMNS - as colunas à direita das células inseridas são movidas para a direitaestas constantes definem o deslocamento das células adjacentes.

copyRange (mDest As < com.sun.star.table.CellAddress >, mOrig As < com.sun.star.table.CellRangeAddress > )copia o grupo de células de mOrig para mDest no mesmo documento.

moveRange ( mDest As < com.sun.star.table.CellAddress >, mOrig As < com.sun.star.table.CellRangeAddress > )move o grupo de células mOrig para mDest, o conteúdo de mOrig é apagado.

removeRange ( mEndereco As < com.sun.star.table.CellRangeAddress >, nModo As Integer )remove o grupo de células de mEndereco; os valores de nModo estão definidos na enumeração < com.sun.star.sheet.CellDeleteMode >:

NONE - nenhuma célula será movidaUP - as células abaixo das células apagadas são movidas para cimaLEFT - as células à direita das células apagadas são movidas para a esquerdaROWS - as linhas abaixo das células apagadas são movidas para cimaCOLUMNS - as colunas à direita das células apagadas são movidas para a esquerdaestas constantes definem o deslocamento das células adjacentes.

Agora, um exemplo simples para demonstrar o emprego destes componentes da API.

Sub copiaExtensao' exemplo interface sheet.XCellRangeMovement Dim oDoc As Object Dim oPlan As Object Dim oExt As Object Dim mDest As New com.sun.star.table.CellAddress Dim mEnd As New com.sun.star.table.CellRangeAddress oDoc = ThisComponent oExt = oDoc.getCurrentSelection() oPlan = oExt.getSpreadsheet() mEnd = oExt.getRangeAddress() mDest.Sheet = 1 ' Planilha2 mDest.Column = 0 mDest.Row = 0 ' copyRange copia também a formatação da célula oPlan.copyRange(mDest, mEnd)' End Sub

Aqui, obtemos a seleção corrente e copiamos para a Planilha2, tendo como origem a célula A1. Observe que o método copyRange é chamado a partir do objeto Spreadsheet.

7.14 Dados de fontes externas

Uma tarefa comum sobre documentos do Calc é a obtenção de dados de fontes externas. Por exemplo, a vinculação de uma planilha de outro documento ou a importação de dados de um



banco de dados. A seguir, veremos alguns serviços da API do OpenOffice.org, voltados para estas tarefas.

Vínculos

O serviço < com.sun.star.sheet.SpreadsheetDocument > contém as propriedades abaixo, relacionadas com vínculos noutros documentos:

SheetLinks - contém a coleção de vínculos de planilhas no documentoAreaLinks - contém a coleção de vínculos de áreas no documentoDDELinks - contém a coleção de vínculos DDE do documentoEstas coleções podem ser obtidas como abaixo:

oDoc = ThisComponent oVinculos = oDoc.SheetLinks ' obtém os vínculos de planilha do documento

A interface < com.sun.star.sheet.XSheetLinkable > possui os seguintes métodos para definir vínculos com planilhas de outros documentos:

getLinkMode ( ) As < com.sun.star.sheet.SheetLinkMode > setLinkMode ( nModo As < com.sun.star.sheet.SheetLinkMode > )obtém ou define o modo do vínculo

getLinkUrl ( ) As StringsetLinkUrl ( sURL As String ) obtém ou define a URL do recurso ( o documento vinculado )

getLinkSheetName ( ) As StringsetLinkSheetName ( sPlanilha As String )obtém ou define o nome da planilha dentro do documento vinculado

link ( sURL As String, sPlanilha As String, sFiltro As String, sOpcoes As String, nModo As < com.sun.star.sheet.SheetLinkMode > )cria um vínculo com uma planilha, em outro documento, se ele não existir

Os valores possíveis para LinkMode, estão em < com.sun.star.sheet.SheetLinkMode >:

NONE - sem vínculoNORMAL - copia os valores e as fórmulasVALUE - copia os valores, inclusive o resultado das fórmulas

Eis alguns nomes de filtros do OpenOffice.org:

StarOffice XML (Calc) - documentos do Calc no formato XMLMS Excel 97 - documentos do Excel 97/2000/XPMS Excel 95 - documentos do Excel 5.0 / 95Para estes filtros, podemos passar uma cadeia vazia como opção do filtro.

Vejamos um exemplo:

Sub vinculoPlanilha



' Dim oDoc As Object Dim oPlan As Object ' oDoc = ThisComponent oPlan = oDoc.Sheets(0) ' edite sURL para seu sistema: sURL = "file:///d:/nad/openoffice/Intro_OOo_Basic/novo_mat/editaPlan.sxc" sOrigem = "Planilha1" sFiltro = "StarOffice XML (Calc)" sOpcoes = "" ' define o modo nModo = com.sun.star.sheet.SheetLinkMode.NORMAL ' estabelece o vínculo oPlan.link(sURL, sOrigem, sFiltro, sOpcoes, nModo) ' desativa o vínculo oPlan.setLinkMode(com.sun.star.sheet.SheetLinkMode.NONE)'End Sub

Note que definimos os parâmetros e estabelecemos o vínculo. Após executar esta macro, a planilha vinculada será carregada para o documento.

Além de planilhas, é possível vincular uma ou mais áreas de um documento externo a um outro documento.

A principal interface usada para isto, < com.sun.star.sheet.XAreaLinks >, tem os métodos:

insertAtPosition ( aPos As <com.sun.star.table.CellAddress >, sArq As String, sFonte As String , sFiltro As String, sFiltroOp As String )insere uma área vínculada na coleção. Os parâmetros tem os significados:

aPos – posição da célula inicial no documento de destino (estrutura). sArq – Url do recurso (documento de origem). sFonte – endereço da área no documento de origem (por ex: “Planilha1.A1:D10”). sFiltro – nome do filtro usado para converter os dados. sFiltroOp – opções para o filtro as opções de filtro são específicas para alguns tipos de filtro.

removeByIndex ( nIndex )remove a área vinculada da coleção.

Vamos apresentar um exemplo simples, demonstrando esta possibilidade:

Sub vinculoArea' Dim oDoc As Object Dim oPlan As Object Dim oLinks As Object Dim aPos As New com.sun.star.table.CellAddress

oDoc = ThisComponent oPlan = oDoc.Sheets(1) sURL = "file:///d:/nad/openoffice/Intro_OOo_Basic/novo_mat/editaPlan.sxc" sFonte = "Planilha1.A1:E8"



sFiltro = "StarOffice XML (Calc)" sOpcoes = "" ' define a origem da área no destino aPos.Sheet = 1 aPos.Column = 0 aPos.Row = 0 ' obtém coleção oLinks = oDoc.AreaLinks ' insere um vínculo com a área sFonte oLinks.insertAtPosition(aPos, sURL, sFonte, sFiltro, sOpcoes) 'remove o ultimo link oLinks.removeByIndex(oLinks.Count - 1)'End Sub

Inicialmente definimos os parâmetros, depois obtemos a coleção de vínculos, adicionamos o novo vínculo e, por fim, removemos o vínculo.

Se um vínculo permanecer ativo, na próxima carga do documento destino, o operador será informado da sua existência e questionado se deseja, ou não, atualizá-los.

Importando dados de um banco de dados

É possível importar dados, de uma fonte de dados registrada no OpenOffice.org, para uma planilha do Calc. Estes dados podem ser o conteúdo de uma tabela, o resultado de uma consulta ou de um comando SQL.

Esta tarefa é executada pelos métodos da interface com.sun.star.util.XImportable, suportada pelo serviço com.sun.star.sheet.SheetCellRange.

Os métodos de XImportable são:

createImportDescriptor ( bVazio As Boolean ) As < com.sun.star.beans.PropertyValue >Se bVazio for True, cria um descritor vazio, senão retorna as propriedades da última importação.

doImport ( oDescritor ( ) As < com.sun.star.beans.PropertyValue > )importa os dados conforme o descritor

O serviço com.sun.star.sheet.DatabaseImportDescriptor possui as propriedades abaixo:

Propriedade DescriçãoSourceType Tipo da fonte (com.sun.star.sheet.DataImportMode)

DatabaseName Cadeia com o nome da fonte de dados registrada no OOo

SourceObject Cadeia com o nome do objeto dentro da fonte de dados

Os valores possíveis para SourceType são (com.sun.star.sheet.DataImportMode):

NONE - nada será importado



SQL - um comando SQL será passado para SourceObjectTABLE - o nome de uma tabela será passado para SourceObjectQUERY - o nome de uma consulta da fonte de dados será passado para SourceObject

Agora um exemplo. A macro abaixo importa todos os registros resultantes do comando SQL para uma planilha.

Sub importaDadosParaPlanilha' Dim oCelOrigem As Object Dim oDescritor As Variant Dim sFonteDados As String Dim sOrigemDados As String Dim iTipo As Long ' obtem a célula da origem na planilha oCelOrigem = ThisComponent.Sheets(1).getCellByPosition(0,0) ' cria um descritor de importação oDescritor = oCelOrigem.createImportDescriptor(True) ' inicializa variáveis iTipo = com.sun.star.sheet.DataImportMode.SQL sFonteDados = "Bibliography" sOrigemDados = "Select * From biblio" ' define as propriedades do descritor oDescritor(0).Name = "DatabaseName" oDescritor(0).Value = sFonteDados oDescritor(1).Name = "SourceType" oDescritor(1).Value = iTipo oDescritor(2).Name = "SourceObject" oDescritor(2).Value = sOrigemDados ' importa os dados oCelOrigem.doImport(oDescritor()) 'End Sub

Como exercício, altere os valores das variáveis oCelOrigem, iTipo e sOrigemDados, executando novamente a macro.


Banco de Dados Versão 2

8 Banco de Dados

8.1 Introdução

O OpenOffice.org traz um poderoso sistema de conexão com banco de dados. O seu principal objetivo é oferecer uma independência de plataforma, permitindo o acesso a banco de dados de diversos fabricantes.

O mecanismo que o OpenOffice.org usa para atingir o seu objetivo é chamado SDBC (Star Database Connectivity), que permite a escrita de “drivers” SDBC específicos para diferentes fontes de dados. Estes “drivers” podem, inclusive, usar padrões de acesso a dados bem estabelecidos, como ODBC e JDBC.

Deste modo, qualquer banco de dados que suporte um dos padrões acima, pode ser definido como uma fonte de dados para o OpenOffice.org. O OpenOffice.org também acessa, nativamente, tabelas do Dbase e Planilhas do Calc, como fonte de dados.

Dentre as facilidades de acesso a banco de dados do OpenOffice.org podemos citar: o uso da SQL (Linguagem de Consulta Estruturada) para consultas e o uso de vínculos e formulários baseados em documentos do OpenOffice.org.

Se você não tem experiência com banco de dados, antes de continuar, procure se familiarizar com as ferramentas gráficas do OpenOffice.org para acesso a fonte de dados. Selecione Ver – Navegador Fonte de Dados. Nesta janela, podemos selecionar uma fonte de dados registrada e operar sobre suas tabelas, consultas e vínculos. Para administrar as fontes de dados, selecione Ferramentas – Fonte de Dados.

8.2 Fontes de Dados

Antes de podermos usar um banco de dados, precisamos registrar a fonte de dados no OpenOffice.org. Pela interface gráfica esta tarefa é executada no diálogo Administração das Fontes de Dados (Menu Ferramentas / Fonte de Dados). Neste diálogo, notamos que uma fonte de dados contém quatro tipos básicos de informações:

a) Geral – sobre os aspectos da conexão com o banco de dados;

b) Tabelas – quais tabelas serão utilizadas;

c) Consultas – os comandos SQL disponíveis;

d) Vínculos – ligações com documentos do OpenOffice.org, por exemplo formulários.

Os principais serviços e interfaces da API do OpenOffice.org, relacionados com banco de dados estão agrupados nos módulos:

com.sun.star.sdb - com.sun.star.sdbcx - com.sun.star.sdbc


Versão 2 Banco de Dados

Vejamos alguns serviços, relacionados com as fontes de dados. O ponto de entrada é o contexto de banco de dados, representado pelo serviço com.sun.star.sdb.DatabaseContext.

Para criar um objeto DatabaseContext, chamamos a função createUnoService ( ):

oContexto = createUnoService ( “com.sun.star.sdb.DatabaseContext” )

Podemos obter as fontes de dados registradas, usando os métodos relacionados com as interfaces XNameAccess e XEnumeration, eis alguns deles:

hasByName ( sNome As String ) As Boolean getByName ( sNome As String ) As Variant getElementNames ( ) As String ( ) hasElements ( ) As Boolean hasMoreElements ( ) As Boolean nextElement ( ) As Variant

Lembre-se que, antes de usar os métodos de XEnumeration, uma enumeração deve ser criada com uma chamada ao método createEnumeration ( ).

Já temos as ferramentas necessárias para escrever um exemplo. Vamos exibir os nomes das fontes de dados registradas em nosso contexto de banco de dados. Digite a Sub contextoBancoDados, abaixo, e execute para ver o resultado.

Sub contextoBancoDados' Dim oContexto As Variant Dim sNomes() As String ' ' cria o contexto de banco de dados oContexto = createUnoService("com.sun.star.sdb.DatabaseContext") If oContexto.hasElements() Then ' obtem os nomes das fontes de dados sNomes = oContexto.getElementNames() ' exibe os nomes das fontes de dados sMsg = "" For i = LBound(sNomes) to UBound(sNomes) sMsg = sMsg + sNomes(i) + Chr$(13) Next i MsgBox sMsg Else MsgBox "Nenhuma fonte registrada" End If'End Sub

Outro serviço da linha de frente é com.sun.star.sdb.DataSource, que representa um objeto fonte de dados. Ele tem várias propriedades e oferece diversas interfaces.

Antes de adicionar uma nova fonte de dados ao contexto, precisamos criar um objeto DataSource. Isto pode ser feito de duas maneiras:



oFonte = oDataContext.createInstance ( ) ' em desuso oFonte = createUnoService ( “com.sun.star.sdb.DataSource” )

Para obter, apagar ou registrar uma fonte de dados no contexto de banco de dados, devemos usar os métodos da interface com.sun.star.uno.XNamingService do objeto DatabaseContext.

getRegisteredObject ( sNome As String ) As < com.sun.star.uno.XInterface > retorna o objeto fonte de dados com o nome sNome

registerObject ( sNome As String, oFonte As < com.sun.star.uno.XInterface >) registra o objeto oFonte como uma fonte de dados com o nome sNome

revokeObject ( sNome As String ) revoga a fonte de dados com o nome sNome

Eis algumas das propriedades do serviço com.sun.star.sdb.DataSource:

Propriedade DescriçãoName Nome da fonte de dados

URL URL do banco de dados (sdbc:subprotocolo:subname ou jdbc ...)

User Nome de login do usuário

Password Senha do usuário

IsPasswordRequired Se True, uma senha será necessária

IsReadOnly Se True, acesso somente para leitura

Vamos retomar o nosso exemplo e acrescentar código para adicionar uma nova fonte de dados ao contexto de banco de dados. Acrescente o código abaixo na Sub contextoBancoDados, execute a macro e verifique, através de Ferramentas – Fonte de Dados, se a nova fonte foi criada.

' ADICIONA UMA NOVA FONTE DE DADOS Dim oFonte As Variant ' cria uma instancia de fonte de dados oFonte = createUnoService("com.sun.star.sdb.DataSource") ' oFonte = oContexto.createInstance() ' testa se a fonte já está registrada If oContexto.hasByName("Minha_Fonte") Then MsgBox "Minha_Fonte já registrada!" Exit Sub Else ' registra a nova fonte no contexto oContexto.registerObject("Minha_Fonte", oFonte) ' define a propriedade URL >>>> ALTERE PARA O SEU SISTEMA <<<< oFonte.setPropertyValue("URL", _ "sdbc:dbase:file:///D:/NAD/OPENOFFICE/BDados") End If



O objeto DataSource suporta algumas interfaces relacionadas com os tipos básicos de informações da fonte de dados, seguem as principais:

A interface com.sun.star.util.XFlushable, relacionada com o fluxo de dados entre o objeto e o banco de dados, contendo os métodos:

flush ( )encaminha os dados do objeto conectado para o banco de dados

addFlushListener ( )removeFlushListener ( ) adiciona e remove “listeners” para o evento “flushed”

A interface com.sun.star.sdb.XQueryDefinitionsSupplier, com o método:

getQueryDefinitions ( ) As < com.sun.star.container.XNameAccess >retorna o recipiente com as consultas definidas numa fonte de dados.

Através da interface com.sun.star.sdb.XBookmarksSupplier, podemos obter os vínculos dos documentos associados a uma fonte de dados, com uma chamada ao método:

getBookmarks ( ) As < com.sun.star.container.XNameAccess >retorna uma coleção de cadeias com a localização dos documentos vinculados.

Vamos obter a nossa recém-criada fonte de dados e fazer algumas verificações. Crie a sub-rotina Sub infoFonteDados e execute, observando a saída.

Sub infoFonteDados' Dim oContexto As Variant Dim oFonte As Variant Dim oConsultas As Object Dim oVinculos As Object Dim sNomes() As String ' ' cria o contexto de banco de dados oContexto = createUnoService("com.sun.star.sdb.DatabaseContext") ' obtem o objeto fonte de dados oFonte = oContexto.getRegisteredObject("Minha_Fonte") ' ' obtem a propriedade TableFilter sMsg = "Tabelas: " + Chr$(10) sNomes = oFonte.getPropertyValue("TableFilter") If UBound(sNomes) > 0 Then For i = 0 To UBound(sNomes) sMsg = sMsg + sNomes (i) + Chr$(10) Next i MsgBox sMsg Else MsgBox "Nenhuma Tabela para visualizar" End If ' ' verifica consultas oConsultas = oFonte.getQueryDefinitions() If oConsultas.getCount() > 0 Then MsgBox Str$(oConsultas.getCount()) + " consultas definidas"



Else MsgBox "Nenhuma consulta definida." End If ' ' verifica vínculos oVinculos = oFonte.getBookmarks() If oVinculos.getCount() > 0 Then MsgBox Str$(oVinculos.getCount()) + " vínculos definidos" Else MsgBox "Nenhum vínculo definido." End If'End Sub

Note que as tabelas a serem visualizadas pela fonte de dados é uma propriedade de DataSource, enquanto as consultas e vínculos são obtidos através de métodos específicos.

8.3 Conexões

Até o momento, trabalhamos dentro do contexto de banco de dados. Se a nossa tarefa estiver relacionada com os dados armazenados no banco de dados ou com a sua estrutura, devemos estabelecer uma conexão com o mesmo.

Uma conexão é um canal de comunicação entre o usuário e o banco de dados, permitindo a transferência de dados entre eles. Este é o principal objetivo do serviço DataSource e, para isto, dispõe das seguintes interfaces e métodos:

A interface com.sun.star.sdb.XCompletedConnection, possui o método:

connectWithCompletion ( oManip As < com.sun.star.task.XInteractionHandler > ) As <com.sun.star.sdbc.XConnection>tenta estabelecer uma conexão com o banco de dados, se necessário, solicita informações.

A interface com.sun.star.sdbc.XDataSource, tem os seguintes métodos:

getConnection( sUser As String, sSenha As String) As < com.sun.star.sdbc.XConnection >tenta estabelecer uma conexão com o banco de dados.

setLoginTimeout ( iSegundos As Long)define o período, em segundos, para tentar estabelecer a conexão

getLoginTimeout ( ) As Longobtém o período, em segundos, para tentar de estabelecer a conexão

Os métodos connectWithCompletion () e getConnection () retornam um objeto, que representa uma conexão. Este objeto, por sua vez, suporta outros serviços e interfaces.

Uma das principais interfaces do serviço com.sun.star.sdb.Connection é XConnection, com métodos para diversas operações. A seguir, alguns deles:

setAutoCommit ( bSinal As Boolean )getAutoCommit ( ) As Boolean



commit ( ) rollback ( )isClosed ( ) As BooleangetMetaData ( ) As < com.sun.star.sdbc.XDatabaseMetaData >setReadOnly ( sSinal As Boolean )isReadOnly ( ) As Boolean

A interface com.sun.star.sdbc.XDatabaseMetaData, retornada por getMetaData ( ), define vários métodos para obter informações sobre o banco de dados e sua estrutura. Seguem alguns:

getUserName ( ) As StringgetDatabaseProductName ( ) As StringgetDriverName ( ) As StringgetTables ( ) As < com.sun.star.sdbc.XResultSet >getColumns ( ) As < com.sun.star.sdbc.XResultSet >getNumericFunctions ( ) As StringgetStringFunctions ( ) As StringgetSystemFunctions ( ) As StringgetTimeDateFunctions ( ) As StringsupportsExpressionsInOrderBy ( ) As BooleansupportsGroupBy ( ) As BooleansupportsOuterJoins ( ) As BooleansupportsStoredProcedures ( ) As Boolean

Vejamos um exemplo, que estabelece uma conexão com uma fonte de dados, obtém e exibe meta dados. Digite o código fonte abaixo e execute a macro.

Sub obtemMetaData' Dim oContexto As Variant Dim oFonte As Object ' cria o contexto de bases de dados oContexto = createUnoService( "com.sun.star.sdb.DatabaseContext") ' obtem a fonte de dados (usa acesso nomeado) oFonte = oContexto.getByName("Minha_Fonte") ' faz a conexão com a fonte de dados Dim oConexao As Object ' If oFonte.IsPasswordRequired () Then Dim oManip As Variant oManip = createUnoService("com.sun.star.sdb.InteractionHandler") oConexao = oFonte.ConnectWithCompletion(oManip) Else oConexao = oFonte.getConnection("","") End If ' obtem meta dados Dim oMetaData As Object oMetaData = oConexao.getMetaData() ' exibe meta dados



MsgBox oMetaData.getURL() + Chr$(10) + _ oMetaData.isReadOnly() + Chr$(10) + _ oMetaData.supportsANSI92EntryLevelSQL() + Chr$(10) + _ oMetaData.supportsSelectForUpdate() + Chr$(10) + _ oMetaData.getMaxColumnNameLength()'End Sub

Note que, se uma senha for requerida, usamos o método connectWithCompletion (), senão chamamos getConnection (). Após estabelecer a conexão, chamamos getMetaData () para obter os meta dados. No final, chamamos alguns métodos de XDatabaseMetaData para exibir informações do banco de dados.

O serviço Connection inclui, também, o serviço com.sun.star.sdbcx.DatabaseDefinition, com outras interfaces. Por enquanto, nos interessa com.sun.star.sdbcx.XTablesSupplier e seu método:

getTables ( ) As < com.sun.star.container.XNameAccess > retorna um container com as tabelas ativas na fonte de dados.

Eis uma chamada a este método:

' obtem a coleção de tabelas (ativas) da fonte de dados oTabelas = oConexao.getTables()

Nas próximas seções, apresentaremos outros métodos suportados pelo objeto Connection.

8.4 Estrutura do Banco de Dados

Nesta seção, vamos apresentar alguns serviços e interfaces, relacionados com a definição, alteração e coleta de informações sobre a estrutura do banco de dados. Normalmente, isto é feito através da linguagem SQL. Porém, no momento, desejamos mostrar alguns serviços do módulo com.sun.star.sdbcx.

Tabelas

As tabelas são os principais componentes da estrutura de um banco de dados e têm uma série de propriedades e elementos associados. Entre eles podemos citar: colunas, chaves primárias e índices.

O ponto de entrada para operações como alteração e recuperação de informações de tabelas são os serviços com.sun.star.sdbcx.Table e com.sun.star.sdb.Table. Eles possuem algumas interfaces e propriedades.

Entre as suas propriedades, todas somente leitura, temos:

Propriedade DescriçãoPrivileges Valor longo contendo os privilégios da tabela



Name Cadeia com o nome da tabela

CatalogName Cadeia com o nome do catálogo

SchemaName Cadeia com o nome do esquema

Description Cadeia com descrição adicional

Type Cadeia com o tipo da tabela

O grupo de constantes com.sun.star.sdbcx.Privilege, define alguns privilégios de operação sobre uma tabela: SELECT, INSERT, UPDATE, CREATE, ALTER, DELETE, DROP, READ, REFERENCE.

O serviço com.sun.star.sdb.DataSettings contém propriedades relacionadas com a exibição dos dados da tabela, como filtro e ordenação. Eis algumas:

Propriedade DescriçãoFilter Cadeia com um filtro de dados adicional

ApplyFilter Se True, aplica o filtro

Order Cadeia descrevendo um tipo de ordenação

As tabelas de uma fonte de dados são obtidas através do objeto Connection e do método getTables, já apresentado, como abaixo:

oConexao = oFonte.getConnection(””,””) oTabelas = oConexao.getTables ( )

O serviço com.sun.star.sdbcx.Column traz propriedades (somente leitura), que descrevem as características de uma coluna. Entre as quais:

Propriedade DescriçãoName O nome da coluna

Type O tipo de dado da coluna ( com.sun.star.sdbc.DataType )

Precision O número de dígitos da coluna ( largura )

Scale Número de dígitos à direita do ponto decimal

IsAutoIncrement Se True, a coluna é incrementada automaticamente

IsCurrency Se True, o valor representa uma moeda

Description Descrição da coluna

Obtemos as colunas de uma tabela pela interface com.sun.star.sdbcx.XColumnsSupplier:

getColumns() As < com.sun.star.container.XNameAccess > retorna um recipiente com as colunas da tabela.



A interface com.sun.star.sdbcx.XKeysSupplier e seu método:

getKeys () As < com.sun.star.container.XIndexAccess > retorna um recipiente com as chaves da tabela.

A interface com.sun.star.sdbcx.XIndexesSupplier fornece os índices de uma tabela:

getIndexes () As < com.sun.star.container.XNameAccess > retorna um recipiente com os índices da tabela.

A interface com.sun.star.sdbcx.XRename é usada para renomear uma tabela:

rename ( sNovoNome As String ) renomeia o objeto

A interface com.sun.star.sdbcx.XAlterTable tem os métodos:

alterColumnByName ( sNome As String, oDesc As < com.sun.star.beans.XPropertySet > ) alterColumnByIndex ( iInd As Long, oDesc As < com.sun.star.beans.XPropertySet > ) ambos alteram uma coluna, o primeiro pelo Nome e o segundo pelo índice, o parâmetro oDesc contém o descritor da coluna com as novas propriedades.

Vejamos um exemplo, que apresenta informações sobre as tabelas da fonte de dados Bibliography, distribuída com o OpenOffice.org.

Sub exibeInfoTabelas' Dim oContexto As Variant Dim oFonte As Object ' cria o contexto de bases de dados oContexto = createUnoService( "com.sun.star.sdb.DatabaseContext") ' obtem a fonte de dados oFonte = oContexto.getByName("Bibliography") ' faz a conexão com a fonte de dados Dim oConex As Object oConex = oFonte.getConnection("","") ' obtem info sobre tabelas e colunas Dim oTabelas As Object Dim oTab As Object Dim oColunas As Object Dim oCol As Object ' obtem a coleção de tabelas (ativas) da fonte de dados oTabelas = oConex.getTables() ' For i = 0 To oTabelas.Count-1 ' obtem a tabela pelo seu índice oTab = oTabelas.getByIndex(i) sMsg = "TABELA: " + oTab.getName() + Chr$(10) + "COLUNAS:" ' obtem a coleção de colunas da tabela oColunas = oTab.getColumns() sNomeColunas = oColunas.getElementNames() ' For j = 0 To UBound(sNomeColunas) oCol = oColunas.getByName(sNomeColunas(j)) sTipo = oCol.getPropertyValue("TypeName") sMsg = sMsg + Chr$(10) + sNomeColunas(j) + " - " + sTipo



Next j MsgBox sMsg ' Next i'End Sub

Após a conexão, pegamos a coleção de tabelas com getTables. A seguir, para cada tabela, obtemos as suas colunas com getColumns e os nomes com getElementNames. Depois, visitamos cada coluna obtendo a propriedade TypeName. No final, exibimos as informações da tabela.

Para a criação de uma tabela, dispomos do serviço com.sun.star.sdbcx.TableDescriptor, que contém as propriedades abaixo:

Propriedade DescriçãoName Nome do objeto a ser criado (do serviço Descriptor)

CatalogName Cadeia com o nome do catálogo

SchemaName Cadeia com o nome do esquema

Description Cadeia com descrição adicional

O serviço com.sun.star.sdbcx.ColumnDescriptor tem várias propriedades, seguem algumas:

Propriedade DescriçãoName O nome da coluna

Type O tipo de dado da coluna ( com.sun.star.sdbc.DataType )

Precision O número de dígitos da coluna ( largura )

Scale Número de dígitos à direita do ponto decimal

IsAutoIncrement Se True, a coluna é ncrementada automaticamente

IsNullable Define o nulo da coluna ( com.sun.star.sdbc.ColumnValue )

Description Breve descrição da coluna

A interface com.sun.star.sdbcx.XDataDescriptorFactory, cria um descritor de dados para um dado objeto, através do método:

createDataDescriptor() As < com.sun.star.beans.XPropertySet > retorna um descritor de dados para o objeto associado. Por exemplo: se chamado por um container de tabelas, cria um descritor de tabela; se chamado por um objeto contendo as colunas de uma tabela, cria um descritor de coluna.

A interface com.sun.star.sdbcx.XAppend, usada para criar e adicionar um novo objeto num recipiente, contém o método:



appendByDescriptor ( oDesc As < com.sun.star.beans.XPropertySet >) cria um novo objeto, usando o descritor oDesc, e adiciona este objeto a um recipiente.

Demonstrando o uso destas informações, vamos criar uma macro para adicionar duas tabelas na fonte de dados Minha_Fonte, criada anteriormente.

Sub criaTabelasMinhaFonte' Dim oContexto As Variant Dim oFonte As Variant

oContexto = createUnoService("com.sun.star.sdb.DatabaseContext") ' obtem a fonte de dados If oContexto.hasByName("Minha_Fonte") Then oFonte = oContexto.getByName("Minha_Fonte") Else MsgBox "Não existe, saindo ..." Exit Sub End If ' faz a conexão com a fonte de dados Dim oConex As Object oConex = oFonte.getConnection("","") ' obtem tabelas da fonte de dados oTabelas = oConex.getTables() ' cria um descritor de dados para a tabela amigos.dbf oTab = oTabelas.createDataDescriptor() ' define propriedade nome oTab.Name = "amigos" ' obtem colunas da tabela oColunas = oTab.getColumns() ' cria um descritor de dados para uma coluna oCol = oColunas.createDataDescriptor() ' define as propriedades da 1a. coluna oCol.Name = "CODIGO" oCol.Type = com.sun.star.sdbc.DataType.DECIMAL oCol.Precision = 5 ' adiciona a coluna ao container de colunas oColunas.appendByDescriptor(oCol) ' define propriedades da 2a. coluna (oCol preserva os valores) oCol.Name = "NOME" oCol.Type = com.sun.star.sdbc.DataType.VARCHAR oCol.Precision = 50 oColunas.appendByDescriptor(oCol) ' define propriedades da 3a. coluna oCol.Name = "ANIV" oCol.Type = com.sun.star.sdbc.DataType.DATE oColunas.appendByDescriptor(oCol) ' ' adiciona a tabela Amigos ao container de tabelas oTabelas.appendByDescriptor(oTab) ' ' cria um descritor de dados para a tabela fones.dbf oTab = oTabelas.createDataDescriptor() ' define propriedade nome



oTab.Name = "fones" ' obtem colunas da tabela oColunas = oTab.getColumns() ' cria um descritor de dados para uma coluna oCol = oColunas.createDataDescriptor() oCol.Name = "CODIGO" oCol.Type = com.sun.star.sdbc.DataType.DECIMAL oCol.Precision = 5 oCol.Description = "Código do amigo" oColunas.appendByDescriptor(oCol) oCol.Name = "FONE" oCol.Type = com.sun.star.sdbc.DataType.VARCHAR oCol.Precision = 15 oCol.Description = "Fone do amigo" oColunas.appendByDescriptor(oCol) ' ' adiciona a tabela ao container de tabelas oTabelas.appendByDescriptor(oTab) ' ' encerra a conexão oConex.dispose()'End Sub

Após a conexão, chamamos o método getTables, que retorna um container oTabelas, com as tabelas ativas na fonte de dados. Depois, criamos o descritor oTab, da nova tabela e chamamos o método getColumns, criando o container vazio oColunas, para as colunas da nova tabela. A seguir, o descritor oCol é criado, suas propriedades definidas e, depois, adicionado a oColunas. Isto é repetido para cada nova coluna, aproveitando o mesmo descritor. Em seguida, acrescentamos o descritor da nova tabela ao container oTabelas. Por fim, repetimos o processo para uma segunda tabela e, para evitar problemas, encerramos a conexão.

Chave Primária

Uma chave primária é quase obrigatoria em bancos de dados relacionais, principalmente no suporte de algumas operações como integridade referencial.

Através do serviço com.sun.star.sdbcx.Key, que oferece as interfaces XColumnsSupplier e XDataDescriptorFactory, podemos extrair as informações de uma chave primária. Ele possui as propriedades abaixo, todas somente leitura:

Propriedade DescriçãoName Nome da chave

Type Tipo da chave (PRIMARY, UNIQUE, FOREIGN)

ReferencedTable Nome da tabela, somente para chaves externas

UpdateRule Regra de atualização, somente para chaves externas



DeleteRule Regra de deleção, somente para chaves externas

Os tipos possíveis para uma chave estão definidos em com.sun.star.sdbcx.KeyType.

As regras são definidas em com.sun.star.sdbc.KeyRule, por ex: CASCADE, RESTRICT, etc.

O serviço com.sun.star.sdbcx.KeyColumn, inclui o serviço Column e tem a propriedade:

RelatedColumn - nome da coluna relacionada numa tabela externa

Para a criação de chaves primárias, temos o serviço com.sun.star.sdbcx.KeyDescriptor, que inclui o serviço Descriptor, oferece a interface XColumnsSupplier e tem as mesmas propriedades do serviço Key, acima, sem a restrição de somente leitura.

O serviço com.sun.star.sdbcx.KeyColumnDescriptor, inclui o serviço Descriptor, e tem as propriedades:

Propriedade DescriçãoName Nome da coluna ( de Descriptor )

RelatedColumn Nome da coluna relacionada numa tabela externa

O trecho de código abaixo (não testado), cria uma chave primária para uma tabela:

' ' Código para criar uma Chave Primária

' ' obtem o recipiente com as chaves oChaves = oTabela.getKeys () ' cria um descritor para a chave primária: oChave = oChaves.createDataDescriptor() ' define propriedades da chave oChave.setPropertyValue("Type", com.sun.star.sdbcx.KeyType.PRIMARY) ' obtem as colunas da nova chave oColunasChaves = oChave.getColumns() ' crai um descritor ( só é preciso um ) oColChave = oColunasChaves.createDataDescriptor() ' define a propriedade oColChave.setPropertyValue("Name", "ID") ' adiciona a coluna chave oColunasChaves.appendByDescriptor(oColChave) ' adiciona a chave oChaves.appendByDescriptor(oChave) ' adiciona a tabela ao container de tabelas oTabelas.appendByDescriptor(oTabela)

Normalmente, esta operação é executada durante a criação da nova tabela, motivo da última linha de código.



Índices

Através do serviço com.sun.star.sdbcx.Index, podemos obter informações sobre um índice de tabela. Ele fornece as interfaces XDataDescriptorFactory e XColumnsSupplier e possui as propriedades a seguir:

Propriedade DescriçãoName Nome do índice

Catalog Nome do catálogo do índice

IsUnique Se True, não aceita valores repetidos na coluna

IsPrimaryKey Se True, o índice é usado como chave primária

IsClustered Se True, indica que o índice é “clustered”

O serviço com.sun.star.sdbcx.IndexColumn, que também inclui o serviço Column, representa as colunas de um índice e tem a propriedade:

IsAscending - Se True, a ordem é ascendente

A criação de novos índices se dá pelo serviço com.sun.star.sdbcx.IndexDescriptor, que inclui o serviço Descriptor, suporta a interface XColumnsSupplier e tem as propriedades:

Propriedade DescriçãoName Nome do índice ( de Descriptor )

Catalog Nome do catálogo do índice

IsUnique Se True, não aceita valores repetidos na coluna

IsClustered Se True, indica que o índice é “clustered”

O serviço com.sun.star.sdbcx.IndexColumnDescriptor, que inclui o serviço Descriptor, permite a criação de colunas para o índice. Ele tem as propriedades:

Propriedade DescriçãoName Nome da coluna ( de Descriptor )

IsAscending Se True, a ordem é ascendente

Vejamos um exemplo que adiciona um índice para a tabela amigos.dbf, criada anteriormente.

Sub criaIndiceAmigos' Dim oContexto As Variant Dim oFonte As Variant

oContexto = createUnoService("com.sun.star.sdb.DatabaseContext")



' obtem a fonte de dados If oContexto.hasByName("Minha_Fonte") Then oFonte = oContexto.getByName("Minha_Fonte") Else MsgBox "Fonte não existe, saindo ..." Exit Sub End If ' faz a conexão com a fonte de dados Dim oConex As Object oConex = oFonte.getConnection("","") ' obtem tabelas da fonte de dados oTabelas = oConex.getTables() If oTabelas.hasByName("amigos") Then ' obtém a tabela amigos.dbf oTabela = oTabelas.getByName("amigos") Else MsgBox "Tabela não existe, saindo ..." Exit Sub End If ' ' obtém os indices da tabela oIndices = oTabela.getIndexes() ' cria um descritor para um novo indice oIndice = oIndices.createDataDescriptor() ' define propriedades do novo indice oIndice.setPropertyValue("Name", "ami_cod") oIndice.setPropertyValue("IsUnique", True) ' obtem as colunas do indice 'oColunas = oIndice.getColumns() oColunas = oIndice.Columns ' cria um descritor de coluna para o indice oColuna = oColunas.createDataDescriptor() ' define as propriedades da coluna oColuna.setPropertyValue("Name", "CODIGO") oColuna.setPropertyValue("IsAscending", True) ' adiciona a nova coluna ao container de colunas oColunas.appendByDescriptor(oColuna) ' adiciona o indice aos indices da tabela oIndices.appendByDescriptor(oIndice) ' ' fecha a conexão oConex.dispose()'End Sub

A lógica para a criação de índices é a mesma já apresentada para a chave primária, com uma diferença: um índice não pode ser adicionado a um descritor de tabela.

Antes de prosseguir, procure, nos exemplos que acompanham esta Introdução, a Sub criaIndiceFone e comande a sua execução, para criar um arquivo índice para a tabela fones.dbf. Note que este índice tem a propriedade IsUnique definida como False.



Segurança

Existem outros elementos, associados à estrutura do banco de dados. Vamos apresentar, brevemente, os relacionados com a sua segurança.

O serviço com.sun.star.sdbcx.Group, representa uma conta para um grupo de usuários. Ele tem a propriedade Nome ( nome do grupo ) e oferece as seguintes interfaces:

Interface com.sun.star.sdbcx.XUsersSupplier com o método:

getUsers ( ) - retorna os usuários do objeto

Interface com.sun.star.sdbcx.XAuthorizable que define os métodos:

getPrivileges ( ) - obtém os privilégios de acesso ao objetogetGrantablePrivileges ( ) - obtém os privilégios, que podem ser concedidos a outrosgrantPrivileges ( ) - concede os privilégiosrevokePrivileges ( ) - revoga os privilégios

O serviço com.sun.star.sdbcx.User representa um usuário do objeto. Possui a propriedade Name ( nome do usuário ) e oferece as interfaces abaixo.

A interface com.sun.star.sdbcx.XUser define o método:

changePassword ( sSenhaAtual As String, sNovaSenha As String ) altera a senha do usuário

A interface com.sun.star.sdbcx.XGroupsSupplier com o método:

getGroups ( )retorna a coleção de grupos do objeto

Para a criação de Grupos e Usuários, temos os serviços GroupDescriptor e UserDescriptor. O raciocínio geral é o mesmo já visto nesta seção para outros descritores.

Finalmente, vamos lembrar que a interface com.sun.star.sdbc.XDatabaseMetaData, fornece uma vasta quantidade de informações sobre o banco de dados. Ela define diversos métodos, alguns já apresentados na seção Conexão.

8.5 Registros

A manipulação dos dados contidos numa tabela pode ser efetuada por duas abordagens diferentes. A primeira, utiliza o serviço RowSet e é usada para fontes registradas no contexto de dados do OpenOffice.org. A segunda, através de uma comunicação direta com o banco de dados, usando um objeto Statement. Nesta seção veremos apenas a primeira delas.



Criando um RowSet

O serviço RowSet utiliza uma conexão para operar sobre tabelas, consultas e comandos SQL. Antes de usá-lo, precisamos definir as suas propriedades e então, executar o seu comando.

O serviço com.sun.star.sdb.RowSet inclui os serviços < sdbc.RowSet > e < sdb.ResultSet >, oferece algumas interfaces e têm uma grande quantidade de propriedades.

Eis algumas propriedades de RowSet:

Propriedade DescriçãoActiveConnection Um objeto Conexão gerada por uma fonte ou URL

DataSourceName Cadeia com o nome da fonte de dados

Command É o comando a ser executado, depende de CommandType

CommandType O tipo de comando, definido em < sdb.CommandType >

Filter O nome de um filtro para o resultado do comando

Order O nome de uma ordenação para o resultado do comando

RowCount Número de registros acessados na base de dados

IsRowCountFinal Se True, indica que todos os registros foram contados

IsNew Se True, indica que o registro será inserido no banco de dados

IsModified Se True, indica que o registro corrente foi alteradoAs quatro últimas propriedades são apenas para leitura.

O grupo < com.sun.star.sdb.CommandType > define as seguintes constantes:

TABLE - indica que Command receberá o nome de uma tabelaQUERY - indica que Command receberá o nome de uma consultaCOMMAND - indica que Command receberá um comando SQL

A interface < XResultSetAccess > define o método:

createResultSet ( ) As < com.sun.star.sdbc.XResultSet > retorna um objeto < ResultSet >

O serviço com.sun.star.sdbc.RowSet, incluído em < sdb.RowSet >, oferece outras interfaces e define outras propriedades. Entre elas:

Propriedade DescriçãoMaxRows Tenta obter o número máximo de linhas

User Nome do usuário para a conexão



Password Senha do usuário para a conexão

ResultSetType O tipo do resultado, de < com.sun.star.sdbc.ResultSetType >

Se necessário “logon”, defina as propriedades User e Password, antes da execução:

oRowSet.setPropertyValue("User", "Maria") oRowSet.setPropertyValue("Password", "senha_de_Maria")

A interface < sdbc.XRowSet > define, entre outros, o método:

execute ( ) preenche o objeto RowSet com os dados

A interface < sdbc.XColumnLocate > permite a localização de colunas com o método:

findColumn ( sNomeCol As String ) As Long a partir do nome da coluna, retorna o seu índice no objeto RowSet.

A interface < sdbc.XParameters > é usada para definir parâmetros em consultas preparadas. Os seus métodos têm a forma setXXX onde XXX é o tipo de dado da coluna.

Vamos a um exemplo de criação de um RowSet, utilizando a tabela biblio, da fonte de dados Bibliography, distribuída com o OpenOffice.org.

Sub criaRowSet' Dim oRowSet As Variant ' cria RowSet oRowSet = createUnoService("com.sun.star.sdb.RowSet") ' define propriedades para conexão com a fonte de dados oRowSet.setPropertyValue("DataSourceName","Bibliography") oRowSet.CommandType = com.sun.star.sdb.CommandType.TABLE ' para TABLE, passamos o nome da tabela oRowSet.setPropertyValue("Command","biblio") ' executa oRowSet.execute() ' verifica se cursor já está no final do resultado MsgBox "O contador está no fim: " + _ oRowSet.getPropertyValue("IsRowCountFinal") ' posiciona no final oRowSet.last() ' verifica de novo MsgBox "O contador está no fim: " + _ oRowSet.getPropertyValue("IsRowCountFinal") ' exibe total de registros no resultado MsgBox "Há " + Str$(oRowSet.getPropertyValue("RowCount")) + _ " registros!" ' destroi o resultado oRowSet.dispose()'End Sub



Note que, para usar o RowSet precisamos: criar um objeto, definir as suas propriedades e, então, chamar o método execute ( ).

Após a criação do objeto RowSet, podemos operar sobre os seus registros, usando as funcionalidades do serviço ResultSet.

Navegando pelos registros

Vamos apresentar algumas interfaces do serviço ResultSet, incluído em RowSet.

A interface XResultSet define métodos de navegação e verificação do registro, são eles:

next ( ) As Booleanfirst ( ) As Booleanlast ( ) As Booleanprevious ( ) As BooleanbeforeFirst ( ) As BooleanafterLast ( ) As Booleanmovimenta o cursor de linha, retorna True em caso de sucesso.

isFirst ( ) As BooleanisLast ( ) As BooleanisBeforeFirst ( ) As BooleanisAfterLast ( ) As Booleanverifica a posição do cursor no ResultSet

getRow ( ) As Longretorna a posição corrente do cursor no ResultSet

absolute ( nLinha As Long ) As Booleanmove o cursor para a linha nLinha, retorna True se bem sucedido

relative ( nLinhas As Long ) As Booleanmove o cursor nLinhas em relação à posição corrente, retorna True se bem sucedido

refreshRow ( )atualiza a linha corrente com os dados mais recentes na fonte de dados

rowUpdated ( ) As BooleanrowInserted ( ) As BooleanrowDeleted ( ) As Booleanverifica o estado do registro ( linha ) corrente.

getStatement ( ) As < com.sun.star.uno.XInterface >retorna o comando que deu origem ao ResultSet.

Acessando os dados

A interface XRow define diversos métodos para acesso aos dados, entre eles:

getString ( nColuna As Long ) As StringgetBoolean ( nColuna As Long ) As BooleangetInt ( nColuna As Long ) As Integer



getFloat ( nColuna As Long ) As SinglegetDouble ( nColuna As Long ) As DoublegetDate ( nColuna As Long ) As < com.sun.star.util.Date >getTime ( nColuna As Long ) As < com.sun.star.util.Time >getTimestamp ( nColuna As Long ) As < com.sun.star.util.DateTime >retorna o conteúdo da coluna nColuna

wasNull ( ) As Booleanse True, indica que a última coluna lida com getXXX ( ) contém um NULL

Agora, um exemplo de navegação e acesso aos dados de um RowSet, criado através de um comando SQL:

Sub obtendoDadosRowSet' Dim oRowSet As Variant ' cria RowSet oRowSet = createUnoService("com.sun.star.sdb.RowSet") ' define propriedades para conexão com a fonte de dados oRowSet.setPropertyValue("DataSourceName","Bibliography") oRowSet.CommandType = com.sun.star.sdb.CommandType.COMMAND ' se COMMAND passamos um comando SQL sCmdSQL = "SELECT IDENTIFIER, AUTHOR, TITLE FROM biblio" oRowSet.setPropertyValue("Command", sCmdSQL) ' executa oRowSet.execute() ' obtem indices das colunas nIdent = oRowSet.findColumn("IDENTIFIER") nTitle = oRowSet.findColumn("TITLE") sMsg = "LINHA : IDENT : TÍTULO(S)" + Chr$(10) ' posiciona curso após último registro oRowSet.afterLast() ' percorre os registros, do último para o primeiro Do While (oRowSet.previous()) ' obtem número da linha sLinha = Str$(oRowSet.getRow()) + " " ' obtém o conteúdo das colunas IDENTIFIER e TITLE sIdent = oRowSet.getString(nIdent) sTitle = oRowSet.getString(nTitle) sMsg = sMsg + sLinha + sIdent + " : " + sTitle + Chr$(10) Loop ' exibe os dados MsgBox sMsg ' destroi o RowSet oRowSet.dispose()'End Sub

Observe que o comando SQL recupera três colunas da tabela biblio, mas exibimos apenas duas.



Alterando os dados

A interface XResultSetUpdate, define métodos para a atualização dos registros:

insertRow ( ) insere o registro no ResultSet e no banco de dados, deve estar no modo de inserção.

updateRow ( ) atualiza os dados do registro.

deleteRow ( ) deleta o registro corrente.

cancelRowUpdates ( ) cancela a atualização do registro, se a operação for suportada.

moveToInsertRow ( ) ativa o modo de inserção, guardando a posição do registro atual.

moveToCurrentRow ( ) retorna para o registro atual quando no modo de inserção.

A interface XRowUpdate define métodos para atualizar os dados da linha. Eis alguns:

updateString ( nColuna As Long, sCad As String )updateBoolean ( nColuna As Long, bValor As Boolean )updateInt ( nColuna As Long, iValor As Integer )updateFloat ( nColuna As Long, fValor As Single )updateDouble ( nColuna As Long, dValor As Double )updateDate ( nColuna As Long, oData As < com.sun.star.util.Date > )updateTime ( nColuna As Long, oHora As < com.sun.star.util.Time > )updateTimestamp ( nColuna As Long, oDataHora As < com.sun.star.util.DateTime > )updateNull ( nColuna As Long )atualiza o conteúdo da coluna nColuna, conforme o tipo de dado.

Vejamos um exemplo, que insere cinco registros na tabela amigos.dbf, da fonte de dados Minha_Fonte, criada anteriormente.

Sub insereLinhasRowSet' Dim oRowSet As Variant ' cria RowSet oRowSet = createUnoService("com.sun.star.sdb.RowSet") ' define propriedades para conexão com a fonte de dados oRowSet.setPropertyValue("DataSourceName","Minha_Fonte") oRowSet.CommandType = com.sun.star.sdb.CommandType.TABLE oRowSet.setPropertyValue("Command","amigos") ' executa oRowSet.execute() ' define novos dados Dim relAmig() ' relação de nomes de amigos Dim relAniv() ' relação de datas de aniversário Dim dsData As New com.sun.star.util.Date relAmig = Array( "Ana", "Maria", "José", "Maria", "MárioXXX")



relAniv = Array("10/05/80","01/02/86","05/06/81","05/06/81","20/03/78") ' inicia a inserção das linhas For I = 0 To 4 ' ativa modo de inserção oRowSet.moveToInsertRow() For J = 1 To 3 If (J = 1) Then ' preenche buffer para coluna tipo DECIMAL oRowSet.updateInt( J, I+1 ) ElseIf (J = 2) Then ' preenche buffer para colunas tipo VARCHAR oRowSet.updateString( J, relAmig(I) ) Else ' converte de string para data dAniv = DateValue( relAniv(I)) ' preenche campos da estrutura ( com.sun.star.util.Date ) dsData.Day = Day( dAniv ) dsData.Month = Month( dAniv ) dsData.Year = Year( dAniv ) ' preenche buffer para colunas tipo DATE oRowSet.updateDate( J, dsData ) End If Next J ' escreve buffer na tabela, saindo do modo de inserção oRowSet.insertRow() Next I MsgBox "Registros inseridos: " + Str$(oRowSet.getRow()) ' ' destroi o resultado oRowSet.dispose()'End Sub

A destacar: o emprego do método updateXXX ( ) adequado ao tipo de dado da coluna, a definição dos valores dos campos da estrutura < Date > e o fato de insertRow ( ) encerrar o modo de inserção ativado pelo método moveToInsertRow ( ).

Intencionalmente, inserimos dois registros errados na tabela amigos.dbf. Um, com um erro no nome (MárioXXX), e outro, duplicado (Maria). Vamos corrigir estes erros.

Sub editaRowSet' Dim oRowSet As Variant ' cria RowSet oRowSet = createUnoService("com.sun.star.sdb.RowSet") ' define propriedades para conexão com a fonte de dados oRowSet.setPropertyValue("DataSourceName","Minha_Fonte") oRowSet.CommandType = com.sun.star.sdb.CommandType.TABLE oRowSet.setPropertyValue("Command","amigos") ' executa oRowSet.execute() ' posiciona na linha duplicada If oRowSet.absolute(4) Then



oRowSet.deleteRow() Else MsgBox "Erro: Saindo..." Exit Sub End If ' posiciona antes da primeira linha oRowSet.beforeFirst() Do While (oRowSet.next()) sNome = oRowSet.getString(2) ' coluna NOME é a segunda If sNome = "MárioXXX" Then oRowSet.updateString(2, "Mário") oRowSet.updateRow() Exit Do End If Loop MsgBox rowUpdated() ' ' destroi o resultado oRowSet.dispose()'End Sub

Inicialmente, apagamos o registro duplicado e em seguida, localizamos e corrigimos o nome na coluna, o método updateRow grava as alterações de updateString.

Obtendo Metadados do RowSet

A interface XResultSetMetaDataSupplier é utilizada para obter informações genéricas sobre o objeto ResultSet e define o método:

getMetaData ( ) As < com.sun.star.sdbc.XResultSetMetaData > O objeto retornado por getMetaData suporta diversos métodos, entre eles:

getColumnCount ( ) As Longretorna o número de colunas do ResultSet.

getColumnName ( nColuna As Long ) As Stringretorna o nome da coluna nColuna.

getPrecision ( nColuna As Long ) As Longretorna a precisão da coluna nColuna.

getScale ( nColuna As Long ) As Longretorna a quantidade de dígitos após o separador decimal.

getTableName ( nColuna As Long ) As Stringretorna o nome da tabela da coluna nColuna, útil em resultados com mais de uma tabela.

getColumnType ( nColuna As Long ) As Longretorna o tipo SQL da coluna nColuna.



8.6 Consultas

Após a criação de uma fonte de dados, podemos definir e armazenar consultas utilizadas com frequência para a recuperação de dados.

O principal serviço envolvido nesta tarefa é com.sun.star.sdb.Query, que inclui outros serviços e oferece algumas interfaces.

O serviço com.sun.star.sdb.QueryDefinition, contém algumas propriedades, como:

Propriedade DescriçãoName O nome da definição (somente leitura)

Command O comando da consulta, normalmente um comando SELECT

EscapeProcessing Se True, a consulta não deve ser alterada pelo “parser SQL”

O serviço com.sun.star.sdb.DataSettings, contém propriedades relacionadas com a exibição dos dados e já foi apresentado na seção Tabelas.

A interface com.sun.star.sdbcx.XDataDescriptorFactory, define o método:

createDataDescriptor ( ) As < com.sun.star.beans.PropertySet > crai um descritor de dados para o objeto.

A interface com.sun.star.sdbcx.XRename é usada para renomear objetos, através do método:

rename ( sNovoNome As String ) renomeia o objeto.

A interface com.sun.star.sdbcx.XColumnsSupplier obtém as colunas do objeto com o método:

getColumns ( ) As < com.sun.star.container.XNameAccess > retorna as colunas contidas no objeto.

A definição de consultas, se dá através da interface XQueryDefinitionsSupplier e seu método:

getQueryDefinitions ( ) As < com.sun.star.container.XNameAccess > retorna um container com as definições das consultas.

O container retornado suporta o método createInstance( ) para a criação de uma nova consulta ou podemos, ainda, usar a função Basic createUnoService.

Vejamos um exemplo que define uma consulta para a fonte de dados Minha_Fonte.

Sub criaConsulta Dim oContexto As Variant Dim oFonte As Object oContexto = createUnoService( "com.sun.star.sdb.DatabaseContext") oFonte = oContexto.getByName("Minha_Fonte") ' obtem o recipiente com as definições de consultas Dim oDefCons As Object



oDefCons = oFonte.getQueryDefinitions() ' cria uma instancia para uma consulta Dim oConsulta As Object oConsulta = oDefCons.createInstance() ' OU: ' oConsulta = createUnoService ("com.sun.star.sdb.QueryDefinition") ' define as propriedades oConsulta.Command = "SELECT * FROM amigos" ' insere a consulta no recipiente oDefCons.insertByName("Consulta_1", oConsulta) ' verifica MsgBox oDefCons.hasByName("Consulta_1")'End Sub

Observe que não é necessário estabelecer uma conexão para definir novas consultas. As propriedades a serem definidas, são as mesmas do serviço QueryDefinition, já apresentadas.

Consultas podem ser criadas, ainda, através do serviço QueryDescriptor e suas interfaces. A lógica é similar àquela já apresentada na criação de índices para tabelas.

O acesso às consultas, após estabelecer uma conexão, pode ocorrer através da interface XQueriesSupplier e seu método:

getQueries ( ) As < com.sun.star.container.XNameAccess > retorna um container com as consultas.

O exemplo a seguir, cria uma conexão com a fonte de dados e obtém as colunas da consulta armazenada anteriormente.

Sub exibeColunasConsulta Dim oDbCont As Variant Dim oDbFonte As Object

oDbCont = createUnoService( "com.sun.star.sdb.DatabaseContext") oDbFonte = oDbCont.getByName("Minha_Fonte") ' faz a conexão com a fonte de dados Dim oDbCon As Object oDbCon = oDbFonte.getConnection("","") ' obtem o recipiente com as consultas Dim oDefCons As Object oDefCons = oDbCon.getQueries() ' obtem a consulta e suas colunas Dim oConsulta As Object Dim oColunas As Object oConsulta = oDefCons.getByName("Consulta_1") oColunas = oConsulta.getColumns() ' obtem nome da coluna e tipo de dado Dim oCol As Object Dim sNomes() As String sNomes = oColunas.getElementNames() sMsg = "" For i = LBound(sNomes) To UBound(sNomes) oCol = oColunas.getByName(sNomes(i)) sMsg = sMsg + sNomes(i) + " - " + _



oCol.getPropertyValue("TypeName") + Chr$(10) Next i MsgBox sMsg + "Total: " + Str$(i) + " Colunas"End Sub

A execução de uma consulta ocorre através do serviço < RowSet >, de modo análogo ao já apresentado na seção sobre Registros. Vejamos um exemplo.

Sub executaConsulta' Dim oRowSet As Variant ' cria RowSet oRowSet = createUnoService("com.sun.star.sdb.RowSet") ' define propriedades para conexão com a fonte de dados oRowSet.setPropertyValue("DataSourceName","Minha_Fonte") oRowSet.CommandType = com.sun.star.sdb.CommandType.QUERY ' se QUERY passamos o nome de uma consulta oRowSet.setPropertyValue("Command", "Consulta_1") ' executa oRowSet.execute() ' obtem indices das colunas nIdent = oRowSet.findColumn("CODIGO") nNome = oRowSet.findColumn("NOME") sMsg = "LINHA: CODIGO: NOME(S)" + Chr$(10) ' percorre os registros Do While (oRowSet.next()) ' obtem número da linha sLinha = Str$(oRowSet.getRow()) + " " ' obtém o conteúdo das colunas CODIGO E NOME sIdent = oRowSet.getInt(nIdent) sNome = oRowSet.getString(nNome) sMsg = sMsg + sLinha + sIdent + " : " + sNome + Chr$(10) Loop ' exibe os dados MsgBox sMsg ' destroi o RowSet oRowSet.dispose()'End Sub

O único aspecto a destacar é CommandType definida como QUERY e a passagem do nome da consulta para Command. As funcionalidades de RowSet são as mesmas já apresentadas anteriormente.

Como informação, a API do OpenOffice.org oferece, também, ferramentas para a composição de consultas, através do serviço com.sun.star.sdb.SQLQueryComposer e da interface XSQLQueryComposerFactory.



8.7 Comandos SQL

Nesta seção, vamos apresentar os elementos básicos para a execução de comandos SQL e recuperação dos resultados decorrentes destes comandos. Lembre-se que as potencialidades da linguagem SQL dependem diretamente dos mecanismos dos banco de dados.

Uma conexão, através da interface com.sun.star.sdbc.XConnection, permite a criação de um objeto para enviar comandos SQL ao banco de dados, com o método:

createStatement ( ) As < com.sun.star.sdbc.Statement > cria um novo objeto Statement.

Este tipo de objeto é apropriado para a execução de comandos SQL sem parâmetros e comandos que não são executados repetidamente.

O serviço < com.sun.star.sdbc.Statement > oferece, dentre outras, as interfaces XStatement e XMultipleResults. Entre as suas propriedades, temos:

MaxRows - obtém o máximo de linhas, se 0 não há limitaçãoCursorName - nome do cursor SQL, depende do banco de dadosResultSetConcurrency - retorna o tipo de concorrência ( em ResultSetConcurrency )ResultSetType - define a capacidade de rolagem ( em ResultSetType )EscapeProcessing - Se True o comando SQL não será modificado pelo “parser”Os seguintes valores são definidos em com.sun.star.sdbc.ResultSetConcurrency:

READ_ONLY - não pode ser atualizadoUPDATABLE - pode ser atualizadoOs valores abaixo são definidos em com.sun.star.sdbc.ResultSetType:

FORWARD_ONLY - o cursor se move para adianteSCROLL_INSENSITIVE - ambas as direções, insensível a mudançasSCROLL_SENSITIVE - ambas as direções, sensível a mudanças

A interface < com.sun.star.sdbc.XStatement > é usada para a execução de comandos SQL e obtenção do resultado do comando. Possui os métodos:

executeQuery ( sCmdSQL As String ) As ResultSet executa um comando que retorna um resultado simples ( um ResultSet )

executeUpdate ( sCmdSQL As String ) As Longexecuta um comando SQL de atualização, para comandos DDL retorna zero.

execute ( sCmdSQL As String ) As Booleanexecuta um comando SQL que pode retornar múltiplos resultados

getConnection ( )retorna a conexão que originou este comando.

A interface < com.sun.star.sdbc.XMultipleResults > é usada para verificar múltiplos resultados de um comando SQL. Define os métodos:

getResultSet ( ) As < ResultSet >retorna o resultado corrente

getUpdateCount ( ) As Long



retorna o contador de resultados

getMoreResults ( ) As Booleanmove para o próximo comando

Vejamos um exemplo de uso do serviço Statement, que opera sobre a tabela amigos, da fonte de dados Minha_Fonte, retornando as colunas NOME e ANIV dos registros com CODIGO maior ou igual a 2.

Sub exemploSQLSelect' Dim oContexto As Variant Dim oFonte As Object ' cria o contexto de bases de dados oContexto = createUnoService( "com.sun.star.sdb.DatabaseContext") ' obtem a fonte de dados oFonte = oContexto.getByName("Minha_Fonte") ' faz a conexão com a fonte de dados Dim oConexao As Object oConexao = oFonte.getConnection("","") ' obtem o resultado de uma consulta Dim oComando As Object Dim oResultado As Object oComando = oConexao.createStatement() ' define o comando SQL sCmdSQL = "Select NOME, ANIV From amigos Where CODIGO >= 2" ' executa o comando oResultado = oComando.executeQuery(sCmdSQL) ' percorre o resultado sMsg = "" n = 0 Do While ( oResultado.next()) sMsg = sMsg + oResultado.getString(1) + Chr$(10) n = n + 1 Loop MsgBox sMsg + "Linhas: " + Str$(n)'End Sub

Note que: estabelecemos uma conexão, criamos o comando e chamamos o método apropriado, neste caso executeQuery, que retorna um ResultSet. Por fim, percorremos o resultado.

O serviço ResultSet, e suas principais interfaces, já foi apresentado na seção sobre Registros.

A lógica é a mesma para os comandos SQL de atualização ( Insert, Update, Delete ) ou comandos que alterem a estrutura do banco de dados ( Create Table, Drop, etc ). O método executeUpdate retorna o número de linhas para comandos SQL e zero para comandos DDL.

A atualização é possivel, também, através dos métodos das interfaces de ResultSet, como já apresentado na seção sobre Registros.



8.8 Comandos SQL Preparados

Quando um mesmo comando SQL, com ou sem parâmetros, for executado diversas vezes, podemos prepará-lo com antecedência, otimizando a resposta do banco de dados. A principal diferença da abordagem anterior, é que o comando será passado ao banco de dados no momento da sua criação. Assim, quando ele for executado o banco de dados responde imediatamente, sem a necessidade de analisá-lo a cada execução, como acontece com os comandos estáticos.

A interface com.sun.star.sdbc.XConnection, permite a criação de um objeto para enviar comandos SQL, com ou sem parâmetros, ao banco de dados, através do método:

prepareStatement ( sCmdSQL As String ) As < com.sun.star.sdbc.PreparedStatement > cria um novo objeto PreparedStatement.

Cada parâmetro do comando SQL deve ser substituído por uma marca (um sinal de interrogação), por exemplo:

sCmdSQL = “UPDATE tabelaX SET colunaY = ? WHERE colunaZ LIKE ?”representa um comando SQL com dois parâmetros, um na colunaY e outro na colunaZ.

O serviço < com.sun.star.sdbc.PreparedStatement > oferece diversas interfaces, entre elas:

A interface < com.sun.star.sdbc.XPreparedStatement > tem funcionalidade similar a XStatement e define os métodos:

executeQuery ( ) As ResultSet executeUpdate ( ) As Longexecute ( ) As BooleangetConnection ( )Todos com funcionalidade igual aos da interface < XStatement >, mas sem parâmetros.

A interface < com.sun.star.sdbc.XParameters >, encarrega-se da definição dos valores dos parâmetros, contendo vários métodos, entre os quais:

setBoolean ( nIndice As Long, bValor As Boolean )setInt ( nIndice As Long, nValor As Long )setFloat ( nIndice As Long, fValor As Single )setDouble ( nIndice As Long, dValor As Double )setString ( nIndice As Long, sValor As String )setDate ( nIndice As Long, stValor As < com.sun.star.util.Date > )setTime ( nIndice As Long, stValor As < com.sun.star.util.Time > )setTimestamp ( nIndice As Long, stValor As < com.sun.star.util.DateTime > )Define o valor do parâmetro nIndice. Eles são numerados na ordem em que aparecem no comando SQL.

clearParameters ( )limpa os valores dos parâmetros imediatamente

Já dispomos dos elementos para apresentar um exemplo ilustrativo:

Sub parametroSQLSelect'



Dim oContexto As Variant Dim oFonte As Object ' cria o contexto de bases de dados oContexto = createUnoService( "com.sun.star.sdb.DatabaseContext") ' obtem a fonte de dados oFonte = oContexto.getByName("Minha_Fonte") ' faz a conexão com a fonte de dados Dim oConexao As Object oConexao = oFonte.getConnection("","") ' define o comando SQL parametrizado sCmdSQL = "Select * From amigos Where CODIGO >= ?" ' prepara o comando Dim oComando As Object oComando = oConexao.prepareStatement(sCmdSQL) ' define o valor do parâmetro nValor = 2 oComando.setInt(1, nValor) ' o campo é DECIMAL ' obtem o resultado da consulta Dim oResultado As Object oResultado = oComando.executeQuery() ' percorre o resultado sMsg = "" n = 0 Do While ( oResultado.next()) sMsg = sMsg + oResultado.getString(2) + Chr$(10) n = n + 1 Loop MsgBox sMsg + "Linhas: " + Str$(n) ' libera os recursos oComando.close()'End Sub

Observe que o comando SQL é passado como argumento do método prepareStatement, depois definimos o valor do parâmetro com um dos métodos setXXX e, só então, chamamos o método executeQuery.

A lógica para atualizações é a mesma, mas devemos chamar o método executeUpdate.

8.9 Consultas Preparadas

A interface <com.sun.star.sdb.XCommandPreparation> define o método a seguir, que nos permite preparar consultas, com ou sem parâmetros, armazenadas na fonte de dados.

prepareCommand ( sComando As String, nTipo As <com.sun.star.sdb.CommandType> ) As < com.sun.star.sdbc.PreparedStatement > envia um objeto PreparedStatement para o banco de dados

Os parâmetros sComando e nTipo têm o mesmo significado das propriedades Command e CommandType, do serviço RowSet.

Relembrando, < com.sun.star.sdb.CommandType > define as seguintes constantes:

TABLE - indica que sComando receberá o nome de uma tabela



QUERY - indica que sComando receberá o nome de uma consultaCOMMAND - indica que sComando receberá um comando SQL

Após a preparação do comando, ele deverá ser executado com um dos métodos da interface XPreparedStatement. Se a consulta ou o comando SQL tiver parâmetros, cada um deles, deverá ser definido com o método setXXX, apropriado ao seu tipo de dado.

O bloco de código a seguir, demonstra esta abordagem:

' prepara o comando Dim oComando As Object ' Consulta_2 está armazenada na fonte de dados: ' Select * From amigos Where CODIGO >= ? sComando = "Consulta_2" nTipo = com.sun.star.sdb.CommandType.QUERY oComando = oConexao.prepareCommand( sComando, nTipo) ' define o valor do parâmetro nValor = 2 oComando.setInt(1, nValor) ' o campo é DECIMAL ' obtem o resultado da consulta Dim oResultado As Object oResultado = oComando.executeQuery() ' percorre o resultado

Observe que: sComando depende de nTipo, o método prepareCommand retorna um objeto PreparedStatement e a definição do parâmetro da consulta segue o padrão anterior.

8.10 Vínculos

Além de tabelas e consultas, uma fonte de dados permite a definição de vínculos com documentos do OpenOffice.org. Este documentos podem conter formulários ou outros objetos, como campos, dependentes de um banco de dados.

O acesso aos vínculos é possivel através da interface com.sun.star.sdb.XBookmarksSupplier e seu método:

getBookmarks ( ) As < com.sun.star.container.XNameAccess > retorna um container com.sun.star.sdb.DefinitionContainer, contendo os vínculos da fonte de dados.

Podemos adicionar ou remover elementos do container, usando os métodos de XNameContainer.

insertByName ( sNome As String, sMarcador As Variant ) sNome é o nome do vínculo e sMarcador a URL do documento.

removeByName ( sNome As String ) sNome é o nome do vínculo

Os marcadores devem conter o caminho completo do documento na forma file:///caminho.

Para manter a consistência, um exemplo:



Sub vinculosFonteDados Dim oContexto As Variant Dim oFonte As Variant Dim oVinculos As Object ' oContexto = createUnoService("com.sun.star.sdb.DatabaseContext") oFonte = oContexto.getRegisteredObject("Minha_Fonte") ' obtem o container com os vínculos oVinculos = oFonte.getBookmarks() ' adiciona um novo marcador sURL = "file:///D:/NAD/OPENOFFICE/TESTMACROS.SXW" oVinculos.insertByName("Meu_Novo_Vinculo1", sURL) ' obtém as URLs dos vínculos sMsg = "" For I = oVinculos.getCount() To 1 Step -1 sMsg = sMsg + "URL: " + oVinculos.getByIndex(I-1) + Chr$(10) Next I MsgBox sMsg'End Sub

Aqui, adicionamos um vínculo na fonte Minha_Fonte e, em seguida extraímos as URLs dos vínculos registrados na fonte de dados.

De posse da URL de um documento, podemos carregá-lo, conforme o explicado no capítulo Trabalhando com Documentos, usando o método:

loadComponentFromURL ( lista_de_parametros ) consulte o capítulo Trabalhando com Documentos, para mais detalhes.


Apêndice – Linguagem Basic Versão 2

9 Apêndice – Linguagem Basic

A linguagem BASIC (Beginner's All-purpose Symbolic Instruction Code) foi criada no ano de 1963, pelos matemáticos John George Kemeny e Tom Kurtzas, no Dartmouth College. Desde então, pela facilidade de uso e aplicação geral, tornou-se uma das mais populares linguagens de programação de computadores, em todo o mundo.

9.1 Primeiros Passos

Para explicar algumas características do OOo Basic, vamos apresentar e analisar, passo a passo, um exemplo simples de programa.

Antes de iniciar, abra um novo documento do Writer e salve-o como ExemplosBasic. Em seguida, selecione, no menu principal, Ferramentas – Macro. Surge o diálogo Macro, na parte central tem a árvore Macro de. Com a barra de rolagem vertical, localize e selecione o nó ExemplosBasic.sxw ( dê um clique sobre o nome para selecionar ). Agora, clique sobre o botão Novo. Surge o diálogo Novo Módulo, com o nome Module1 na caixa de texto. Clique sobre o botão OK. Pronto, você acabou de criar um novo módulo Module1, para receber a macro do nosso exemplo. A nova janela que surgiu é o editor Basic, parte do IDE Basic do OpenOffice.org. Esta janela, na sua parte central, contém as linhas:

REM ***** BASIC *****

Sub Main

End SubSe você não chegou neste ponto, consulte o capítulo Macros OpenOffice.org Basic, desta Introdução. Lá, existem informações detalhadas sobre o IDE Basic.

Vamos ao nosso exemplo. Ele solicita o nome do operador, obtém a hora do sistema e faz uma saudação apropriada. Digite o código fonte abaixo, entre as linhas Sub Main e End Sub:

Dim sNome As String ' variável para guardar o nome Dim sSauda As String ' variável para guardar a saudação Dim sHora As Integer ' variável para guardar a hora do sistema sHora = Hour ( Now ) sNome = InputBox ( "Digite o seu Nome:", "Caixa de entrada", "Operador" ) If ( sHora > 6 And sHora < 18 ) Then sSauda = "Bom Dia! " Else sSauda = "Boa Noite! " End If MsgBox sSauda + sNome

Você acabou de criar uma macro chamada Main. Vamos executar a macro: selecione, na barra de menu, Ferramentas – Macro. No diálogo Macro, clique sobre o botão Executar. Surge uma caixa de entrada, solicitando o seu nome, digite-o e clique sobre o botão Ok. Surgirá um diálogo com uma saudação, clique em Ok para encerrar a execução da macro. Se ocorrer algum erro, revise o código digitado e recomece.


Versão 2 Apêndice – Linguagem Basic

Vamos analisar, passo a passo, o nosso código fonte:

REM ***** BASIC *****Esta linha contém um comentário. Comentários não são executados.

Sub MainEsta linha declara e define uma sub-rotina chamada Main e deve estar acompanhada de uma linha End Sub. Entre as duas linhas deve vir o código fonte que dá funcionalidade a sub-rotina.

Dim sNome As String ' variável para guardar o nome Dim sSauda As String ' variável para guardar a saudação Dim sHora As Integer ' variável para guardar a hora do sistemaEstas linhas declaram e inicializam as variáveis que serão usadas na macro. O apóstrofe marca o início de comentários numa linha de código.

sHora = Hour ( Now )Aqui, chamamos duas funções internas do Basic. A função Now, obtém a hora completa do sistema (hh:mm:ss). A função Hour recebe o valor retornado por Now e extrai somente a hora. Em seguida, o valor obtido por Hour ( a hora ) é armazenado na variável sHora. Neste contexto, o sinal de igual ( = ) é chamado operador de atribuição. Tudo que estiver do lado direito do operador de atribuição recebe o nome de expressão, neste caso Hour ( Now ).

sNome = InputBox ( "Digite o seu Nome:", "Caixa de entrada", "Operador" )Esta linha chama a função InputBox, do Basic, que apresenta a caixa de diálogo para lidar com a entrada do nome do operador. Note que passamos três cadeias de caracteres para esta função. Estes valores (as cadeias) são chamados de parâmetros da função. O primeiro parâmetro é uma mensagem para o operador, o segundo é o título do diálogo e o terceiro é o valor padrão da caixa de texto. A função InputBox retorna o conteúdo da caixa de texto se você clicar sobre o botão Ok, senão ( clique sobre o botão Cancelar ou Fechar ) retorna uma cadeia vazia. Após encerrar o diálogo, o valor retornado será atribuído à variável sNome.

Ainda, sobre parâmetros, podemos dizer que a função Now não têm parâmetro e que a função Hour recebe um parâmetro.

If ( sHora > 6 And sHora < 18 ) ThenAqui, iniciamos a execução de um comando de decisão. Estamos dizendo ao Basic: se o valor armazenado na variável sHora for maior que 6 e menor que 18 então execute o próximo bloco de código. Os sinais > e < são chamados operadores relacionais. A palavra And é chamada de operador lógico. O conteúdo entre parênteses é uma expressão composta que será avaliada como Verdadeira (True) ou Falsa (False). Ela será verdadeira, se ambas as expressões ( sHora > 6; sHora < 18) forem verdadeiras.

sSauda = "Bom Dia! "A expressão “Bom Dia! ” será atribuída a sSauda, se a expressão da linha anterior for avaliada como verdadeira (True).

ElseSenão, a expressão foi avaliada como falsa (False), execute o próximo bloco de código.

sSauda = "Boa Noite! "A expressão “Boa Noite! ” é atribuída à variável sSauda.

End If



Esta linha indica o final do comando de decisão IF ... THEN ... ELSE ... END IF.

MsgBox sSauda + sNomeEsta linha chama a sub-rotina MsgBox, do Basic, que exibe uma caixa de mensagem para o operador. Ela recebe um parâmetro, neste caso a expressão sSauda + sNome. O sinal ( + ), neste contexto, é chamado de operador de concatenação, pois junta as cadeias de caracteres guardadas nas variáveis sSauda e sNome. Clique sobre o botão OK para fechar a caixa de mensagem.

End SubEsta linha indica o término da sub-rotina, iniciada na linha SUB Main. Não esqueça, uma linha SUB ... precisa estar associada a uma linha END SUB.

Neste tópico, você aprendeu diversos conceitos (estão em negrito) relacionados com a linguagem Basic. Se algum ponto não foi compreendido, execute novamente o exemplo e leia o passo a passo, tentando associar o que ocorreu durante a execução com as linhas de código.

9.2 Elementos do Basic

Nesta seção, veremos superficialmente os principais elementos da linguagem Basic.

Palavras reservadas

Uma palavra reservada é um identificador ( nome ) utilizado internamente pela linguagem Basic. As palavras reservadas do Basic são aquelas usadas nos seus comandos, nas suas funções internas, nas suas constantes e nos seus operadores. Abaixo, alguns exemplos:

BEEP - comando do BasicCALL - comando do BasicSUB - comando do BasicFOR - parte de um comando do BasicNEXT - parte de um comando do BasicEXIT - parte de comandos do BasicWHILE - parte de comandos do BasicDO - parte de comandos do BasicSTR$ - função do BasicTRIM$ - função do BasicSQR - função do BasicAND - operador do BasicOR - operador do BasicPI - constante definida pelo BasicO principal sobre estas palavras é: elas não podem ser usadas como nomes para identificar variáveis, constantes ou procedimentos definidos pelo programador.

Regras para nomes

Devemos observar as seguintes regras para os nomes das nossa variáveis, constantes, sub-rotinas e funções:



Nomes são compostos por letras (A a Z), dígitos (0 a 9) e sublinhado (_);Caracteres especiais e de pontuação não são permitidos ( ex: letras acentuadas, vírgula );Nomes devem começar por uma letra do alfabeto;Nomes não podem conter mais de 255 caracteres;Nomes não diferenciam entre letras maiúsculas e minúsculas;Nomes contendo espaço são permitidos, mas devem estar entre colchetes;Palavras reservadas não podem ser usadas como nomes definidos pelo programador.

Exemplos:

Nomes válidos: ptoIni, ponto2, flag, minha_Funcao, [Minha Variavel]Nomes inválidos: 2_ponto, minha?Variável, ºcelsius, Retângulo, BEEP

Comentários

Numa macro, as linhas iniciadas por apóstrofe ou pela palavra reservada REM ( de REMarker) são consideradas como comentários, portanto não são processadas.

' Isto é um comentário REM O código abaixo inicializa as variáveis de ambiente

Os comentários (com apóstrofe) podem ser colocados na frente de uma linha de código.

DIM coord_X As Double ' variável para guardar a coordenada X do ponto DIM coord_Y As Double ' variável para guardar a coordenada Y do ponto

Tipos de dados internos

Inteiros ( INTEGER )Um inteiro pode conter um valor na faixa de -32768 a 32767.

Inteiros Longos ( LONG )Um inteiro longo pode conter um valor na faixa de -2.147.483.648 a 2.147.483.647.

Ponto flutuante simples ( SINGLE )Valores de precisão simples podem variar de 3.402823E38 a 1.401298E-45, para números positivos ou negativos.

Ponto flutuante duplo ( DOUBLE )Os valores de dupla precisão variam na faixa de 1.797693134862315E308 a 4.94066E-324, para valores negativos ou positivos.

Moeda ( CURRENCY )Os valores deste tipo variam de -922.337.203.685.477,5808 até 922.337.203.685.477,5807.

Booleano ( BOOLEAN )Os valores deste tipo podem ser True (verdadeiro) ou False (falso)

Data ( DATE )Podem conter valores de data e tempo armazenados num formato interno.



Cadeias de caracteres ( STRING )Uma cadeia pode conter até 64000 caracteres ( 64 Kb ).

Declaração de variáveis

Podemos declarar variáveis explicitamente com a palavra reservada DIM, do modo abaixo:

DIM nome_da_variavel AS tipo_de_dadoOu:

DIM nome_da_variavel seguido do caractere indicador do tipo de dadonome_da_variavel é um nome definido pelo programador, conforme as regras de nomeação.

Exemplos:

DIM varInteira AS INTEGER ' Declara uma variavel inteira DIM varInteira% ' Declara uma variavel inteira (%) DIM varIntLongo AS LONG ' Declara uma variavel longa DIM varIntLongo& ' Declara uma variavel longa (&) DIM varString AS STRING ' Declara uma variavel string DIM varString$ ' Declara uma variavel string ($) DIM varSingle AS SINGLE ' Declara uma variavel real simples DIM varSingle! ' Declara uma variavel real simples (!) DIM varDupla AS DOUBLE ' Declara uma variavel real dupla DIM varDupla# ' Declara uma variavel real dupla(#) DIM varPreco AS CURRENCY ' Declara uma variavel moeda DIM varPreco@ ' Declara uma variavel moeda (@)

Podemos declarar uma variável, no momento do seu emprego, acrescentando o caractere de tipo ao nome da variável, como nos exemplos abaixo:

UmInteiro% = 1500 ' declara um inteiro UmLongo& = 2195678 ' declara um inteiro longo MeuNome$ = ´´JOSÉ DE ANDRADE´´ ' declara uma cadeia UmRealSimples! = 15.555 ' declara um real simples UmRealDuplo# = coordEne * sin(30) ' declara um real duplo

Se o tipo de dado não for indicado a variável será assumida como Single.

O valor de uma variável declarada será 0 para tipos numéricos, uma cadeia nula para Strings e False para Boolean.

É recomendável a declaração explícita das variáveis de um programa, bem como a escolha de nomes significativos para as mesmas. Para forçar a declaração de todas as variáveis, use a linha de comando abaixo, no início do módulo:

OPTION EXPLICIT

Matrizes

Matrizes contém um grupo de variáveis com características comuns e com o mesmo tipo de dado. Com uma matriz podemos usar um só nome de variável e acessar os valores de um elemento usando um índice. Uma matriz tem um limite inferior e um limite superior em cada



dimensão. Os índices são valores inteiros (negativos ou positivos). Até 16.368 elementos podem ser endereçados.

Matrizes são estruturas de dados próprias para uso dentro de laços.

Exemplos de emprego de matrizes:

Dim nomeDePonto (30) AS String 'Vetor para 31 nomes de pontos (0 a 30) Dim coordPonto3D# (30, 2) ' Matriz de 2 dimensões com 31 linhas e ' 3 colunas (X, Y e Z) do tipo Double ' Atribuindo valores nomeDePonto(0) = “Ponto01” ' atribui a cadeia ao 1o. elemento do vetor nomeDePonto(30) = “Ponto31” ' atribui a cadeia ao último elemento do vetor ' Acessando valores coordX = coordPonto3D(9,0) ' obtém o valor da linha 10, coluna 1 coordY = coordPonto3D(9,1) ' obtém o valor da linha 10, coluna 2 coordZ = coordPonto3D(9,2) ' obtém o valor da linha 10, coluna 3

Os índices inferior e superior podem ser definidos com a cláusula TO, por exemplo:

Dim sNomes$(1 To 30) ' Declara vetor para 30 (1 a 30) nomes Dim matrizA%(1 To 5, 1 To 3) ' Declara matriz de 5 linhas X 3 colunas

Podemos declarar uma matriz cujo tamanho será determinado posteriormente.

Dim nomePonto$( ) ' Declara um vetor de tamanho desconhecidoApós conhecer o número de pontos, podemos redimensionar o vetor com REDIM:

NumeroPontos = 100Redim nomePonto(numeroPontos) 'redimensiona o vetor para 101 nomes (0 a 100)REDIM apaga o conteúdo do vetor, se quisermos aumentar o tamanho do vetor preservando seu conteúdo, devemos usar a cláusula PRESERVE, veja abaixo:

REDIM PRESERVE nomePonto(200) ' aumenta de 100 para 200 conservando o conteúdo

Escopo das variáveis

O escopo tem a ver com a visibilidade de uma variável dentro da macro, ou seja, os lugares da macro onde esta variável pode ser referenciada. Uma variável pode ser local, pública ou global, conforme a sua declaração. Se ela for declarada dentro de uma sub-rotina ou função ela será visível apenas dentro da sub-rotina ou função, portanto local. Se for declarada fora de qualquer sub-rotina ou função com o comando PUBLIC, ela será visível por todas as sub-rotinas e funções da macro, sendo assim uma variável pública dessa macro. Se for declarada fora de uma sub-rotina ou função com o comando GLOBAL, ela será visível por todas as macros, isto é, preserva o seu valor após o término da execução da macro.

Exemplos do escopo de variáveis:

Global corElemento As Integer ' visível por todas as macros Public estiloLinha As Integer ' visível apenas nesta macro

Sub trocaValor(valor1%, valor2%) Dim temp% ' temp é visível apenas em trocaValor ' ... outros comandos



End Sub

Sub Main Dim var1 As Integer ' visível apenas pela Sub Main pesoLinha% = 2 ' visível apenas pela Sub Main ' ... outros comandos End Sub

A declaração de uma variável pública deve ser feita antes de qualquer sub-rotina ou função na macro.

As variáveis locais existem apenas enquanto a sub-rotina ou função, na qual elas foram declaradas, são executadas.

Constantes simbólicas

Para facilitar a leitura de uma macro, os valores literais (1000, “S”, 2.718), usados ao longo da mesma, devem ser declarados como constantes simbólicas, com o comando CONST, fora de qualquer sub-rotina ou função, assim:

' declaração de constantes Const NR_PONTOS% = 1000 ' número de pontos = 1000 Const SIM$ = “S” ' constante SIM = “S” Const BASE_NATURAL# = 2.718 ' base log. naturais

Posteriormente, podemos usar estas constantes numa expressão, no lugar dos seus valores literais, por exemplo:

DIM coordX (NR_PONTOS) As Double ' declara vetor com 1001 elementos valor# = valor1 * BASE_NATURAL ' bem mais compreensível!

If (Resposta$ = SIM) Then ' se resposta = “S” então ' execute os comandos End If

Após a declaração de uma constante, o seu valor não poderá ser mudado dentro do programa.

Constantes simbólicas facilitam a manutenção do programa, pois você precisa alterar apenas o seu valor, em vez de todas as ocorrências do valor literal dentro do programa.

O OpenOffice.org Basic possui as seguintes constantes pré-definidas ( PI, True, False ).

Expressões

Uma expressão é uma constante, uma variável, uma função, ou qualquer combinação destas, separadas por operadores e parênteses, escrita segundo as regras do Basic e passível de avaliação. Seguem os principais elementos encontrados em expressões.

Operador de Atribuição

O resultado de uma expressão pode ser atribuido a uma variável com o uso do operador de atribuição, o sinal de igual ( = ). Note que neste contexto, o sinal de igual não significa uma



comparação, mas sim uma atribuição, isto é, o resultado da expressão do lado direito do sinal será atribuído à variável do lado esquerdo do sinal. Exemplos:

' declara as variáveis diametro e raio Dim diametro#, raio# ' atribui o valor 2.0 ao raio ( 2.0 é uma expressão ) raio = 2.0 ' atribui o resultado da expressão ( 2 * raio ) a diametro diametro = 2 * raio

Operadores Aritméticos

São usados com operandos numéricos e produzem resultados numéricos. Os operandos podem ser constantes numéricas, variáveis numéricas ou funções que retornam valores numéricos. Os operadores são:

Operador Usado para Operandos+ Somar expressões 2

- Subtrair expressões 2

* Multiplicar expressões 2

/ Dividir a primeira pela segunda expressão 2

\ Dividir expressões inteiras 2

Mod Obter o resto de uma divisão inteira 2

^ Exponenciação 2Exemplos:

' valor = 0.5 ( note que 5 e 10 são promovidos a Double ) valor# = 5/10 ' cos() é uma função interna do Basic cosTeta# = cos (1.555 ) ' PI é uma constante do Basic area# = 2 * PI * raio ^ 2 ' r, a, b, c, d, e são variáveis numéricas r = (a + b) * (c - d / e)

Operadores de Concatenação de Cadeias

São usados para juntar duas ou mais cadeias de caracteres.

Operador Usado para& Concatenar duas ou mais cadeias ( strings )

+ Concatenar duas ou mais cadeias ( strings )

Exemplos:



preNome$ = “Menino” sobreNome$ = “Maluquinho” nomeCompleto$ = preNome & “ “ & sobreNome

Operadores Relacionais ( Comparação )

São usados para comparar expressões e o resultado é um Booleano, True (-1) ou False (0).

Operador Usado para= As expressões são iguais ?

<> As expressões são diferentes ?

> A primeira expressão é maior que a segunda ?

< A primeira expressão é menor que a segunda ?

>= A primeira expressão é maior que ou igual a segunda ?

<= A primeira expressão é menor que ou igual a segunda ?

Na comparação de strings, maiúsculas são diferentes de minúsculas, por padrão.

Exemplos:

' se RioSP for > o resultado da expressão é True, senão False resultado = ( RioSP > RioBH ) ' se Raio1 for = a Raio2 o resultado é True, senão False resultado = ( Raio1 = Raio2 )

Operadores Lógicos

Se usados com operandos Booleanos e/ou expressões Booleanas, resultam num valor Booleano. Se usados com operandos numéricos, executam uma operação bit a bit, resultando num valor numérico.

Operador Usado para OperandosNOT Inverte o resultado booleano 1

OR Uma das expressões é TRUE ? 2

AND Ambas as expressões são TRUE ? 2

XOR Uma expressão é TRUE e a outra FALSE ? 2

EQV Ambas são TRUE ou ambas são FALSE ? 2

IMP Se a 1a. for TRUE a 2a precisa ser TRUE 2

Exemplos:

' ' resultado True, se as 2 expressões forem True



' FIM_ARQUIVO é uma constante definida anteriormente resultado = (NrPtos < 1000 And Not FIM_ARQUIVO) ' ' resultado True se a 1a. ou a 2a. for True ' EOF() é uma função do Basic resultado = (NrPtos < 1000 Or Not EOF())

Para exemplos de operação bit a bit, consulte a ajuda ( Help ) on-line.

Precedência dos Operadores

Uma expressão pode ser composta por mais de um operador. A ordem na qual estes operadores são avaliados chama-se precedência dos operadores, da maior para a menor temos:

( ) Parênteses ^ Exponenciacão *, / Multiplicação e divisão \ Divisão inteira Mod Módulo +, - Soma e subtração =, <>, >, <, >=, <= Operadores relacionais Not, And, Or, Xor, Eqv, Imp Operadores lógicos nesta ordemPara forçar a avaliação de uma expressão podemos, sempre, usar parênteses (maior precedência).

Exemplo:

valor1 = 6 + 6 / 3 ' após avaliação valor1 = 8 valor2 = ( 6 + 6 ) / 3 ' após avaliação valor2 = 4

9.3 Fluxo de controle da execução

A ordem de execução dos comandos, numa macro, é determinada pelos comandos de decisão (IF e SELECT CASE) e repetição (DO, FOR e WHILE) existentes no programa. Além destes, podemos usar Labels, GOTO e GOSUB, quando estritamente necessário.

Comando de decisão If ... Then

Primeira forma do comando IF:

If ( expressão ) Then ' Se expressão for True Então ' ' Execute este bloco de comandos 'End If ‘ Fim SeSegunda forma do comando IF (com a cláusula ELSE):

If ( expressão ) Then ' Se expressão for True Então ' Execute este bloco de comandos



Else ' Execute este bloco de comandosEnd If ' Fim SeTerceira forma do comando IF (com a cláusula ELSE IF):

If (expressão) Then ' Se expressão for True Então ' Execute este bloco de comandosElseIf (expressão) Then ' Execute este bloco de comandosElse ' Execute este bloco de comandosEnd If ' Fim Se

Em todas as formas o uso dos parênteses é opcional. Podemos aninhar vários comandos If.

Exemplo da segunda forma do comando IF:

If (a > b) Then ' se a for > que b, então maior = a ' armazene o valor de a na variavel maior Else ' senão maior = b ' armazene o valor de b na variavel maior End If ' fim se

Exemplo da terceira forma do comando IF:

If (botao = Ok) Then mens$ = “OK pressionado” ElseIf (botao = Cancela) Then mens$ = “CANCELA pressionado” Else

mens$ = “AJUDA pressionado” End If

Comando de decisão Select Case

Forma do comando Select Case ... End Select:

Select Case ( expressão_de_teste ) Case lista_de_expressões1 ' execute este bloco de comandos Case lista_de_expressões2 ' execute este bloco de comandos Case Else ' execute este bloco de comandosEnd Select ' fim da seleção

A instrução Select Case avalia a expressão_de_teste somente uma vez, na entrada do comando, em seguida, compara seu resultado com a lista_de_expressões das cláusulas Case. Se houver uma coincidência, os comandos abaixo do Case serão executados. Os comandos de Case Else (que é opcional) serão executados se não houver nenhuma coincidência anterior.



A lista de expressões pode conter mais de uma expressão ou até uma faixa de valores (Ex: 10 To 20), com cada expressão separada por vírgula. As expressões devem ser do mesmo tipo de dado da expressão_de_teste. Após a execução do bloco de comandos, o controle passa para a próxima linha depois do End Select.

Exemplo de Select Case avaliando constantes:

Select Case tipoDesenho Case LINHA ' executa comandos para linha Case CIRCULO ' executa comandos para círculo Case CURVA ' executa comandos para curva Case Else ' avisa ao operador que o elemento é inválido End Select

Exemplo de Select Case avaliando valores:

Select Case corElemento Case 0 To 2, 6, 8 ' caso cores 0, 1, 2, 6 ou 8 ' executa este bloco de comandos Case 3 To 5 ' caso cores 3, 4 ou 5 ' executa este bloco de comandos Case 9 ' caso cor 9 ' executa este bloco de comandos End Select

Comando de repetição While ... Wend

Forma do comando While ... Wend:

While ( expressão_de_teste ) ' enquanto expressão for True ' ' executa este bloco de comandos ' Wend ' fim enquantoEste comando avalia a expressão_de_teste no início, se o resultado for True, o bloco de comandos será executado e o controle volta para o While para uma nova avaliação da expressão. Senão o comando após o Wend será executado. É permitido aninhar laços While ... Wend.

Exemplo de While ... Wend:

Sub exemplo_While_Wend' Dim nomeArq As String Dim sPasta As String Dim nrArq As Integer ' nrArq = 0 ' inicializa contador de arquivos



sPasta = CurDir() ' obtém a pasta corrente nomeArq = Dir$( sPasta, 0 ) ' obtem nome do primeiro arquivo ' While (nomeArq <> "") ' enquanto tiver nome arquivo ' ' aqui, podemos executar alguma tarefa sobre o arquivo ' nomeArq = Dir$() ' retorna nome do próximo arquivo ou "" nrArq = nrArq + 1 ' incrementa nr de arquivos Wend ' fim enquanto ' MsgBox Str$(nrArq) + " arquivos, na pasta: " + sPasta'End Sub

Neste exemplo, obtemos a pasta corrente e todos os nomes de arquivos, com atributo normal, nela existentes. As funções CurDir, Dir e Str$ são internas ( do Basic ). Note que na primeira chamada da função Dir, passamos dois parâmetros e nas próximas chamadas, dentro do laço, não passamos nenhum parâmetro.

Comando de repetição For ... Next

Forma geral do comando For ... Next:

FOR Contador = valor_inicial TO valor_final STEP valor_incremento ' executa bloco de comandos IF (expressão) THEN ' para sair do laço antes do Contador atingir o valor_final EXIT FOR ' use o comando Exit For END IF ' fim se NEXT Contador ' aqui, Contador é opcionalO comando For ... Next funciona da seguinte maneira:

O valor_inicial é atribuído à variável Contador, depois ele testa o contador com o valor_final, se o resultado do teste for True, os comandos dentro do laço serão executados, em seguida Contador será incrementado com valor_incremento e um novo teste será executado, até que se obtenha um valor False para o teste, conforme as regras:

Para valor do incremento positivo, o teste será True se Contador <= valor_final.Para valor do incremento negativo, o teste será True se Contador >= valor_final.Se a cláusula STEP for omitida o valor_incremento será 1.

O teste com IF deve ser usado se quisermos sair do laço antes que Contador bata com o valor_final.

Exemplo de For ... Next:

' Inicializar um vetor de 100 elementos ' Sub exemplo_For_Next Dim Vetor(1 To 100) As Integer Dim I As Integer '



' para I variando de 1 a 100 com incremento 1 For I = 1 To 100 ' I é usado como índice do vetor e também na expressão Vetor(I) = I * 2 Next I ' vai para a próxima avaliação de I ' exibe resultado da soma do 1o e último elementos MsgBox Str$ ( Vetor(1) + Vetor(100) ) ' End Sub

Aqui, definimos um vetor com 100 elementos, com o índice inicial em 1 e o final em 100 ( se você não especificar o índice inicial, o OOo Basic adota o zero ). Depois, entramos no laço e atribuímos valores ( I * 2 ) para os elementos do vetor. Terminamos exibindo a soma dos primeiro e último elementos do vetor.

O comando For ... Next é muito eficiente e deve ser usado sempre que soubermos o número de repetições do laço.

Podemos aninhar comandos For ... Next ( muito útil para operações com matrizes ).

Comando de repetição Do ... Loop

Empregado para executar um bloco de comandos um número indefinido de vezes. Este comando pode ser usado de 5 maneiras diferentes.

Primeira, laço infinito:

DO ' faça ' executa bloco de comandos ' teste para sair do laço, sem o teste o laço será infinito IF (expressão) THEN EXIT DO ' sai do laço END IF LOOP ' retorna para o DoSegunda, teste no início do comando com WHILE

DO WHILE (expressão) ' faça ENQUANTO expressão for True ' executa bloco de comandos LOOP ' retorna para o DoTerceira, teste no início do comando com UNTIL:

DO UNTIL (expressão) ' faça ATÉ que a expressão seja True ' executa bloco de comandos LOOP ' retorna para o DoQuarta, teste no final do comando com WHILE:

DO ' faça ' executa bloco de comandos LOOP WHILE (expressão) ' ENQUANTO expressão for TrueQuinta, teste no final do comando com UNTIL:

DO ' faça ' executa bloco de comandos



LOOP UNTIL (expressão) 'ATÉ que expressão seja True

Em todas as maneiras podemos colocar um teste no interior do laço, para abandoná-lo com o comando EXIT DO. Note que nas formas iniciadas somente com o DO, o laço será executado pelo menos uma vez. Os Comandos Do ... Loop podem ser aninhados.

Exemplo de Do ... Loop, com o teste da expressão no início:

Do While ( Not Eof() ) ' faça enquanto não for Fim de Arquivo ' leia a linha ' processe a linha Loop ' fim do laço

Exemplo de Do ... Loop, com o teste da expressão dentro do laço:

Do ' faça ' obtem nomePonto If IsNull (nomePonto) Then ' se nome do ponto for nulo Exit Do ' saia do laço End If ' fim se ' processa o ponto Loop ' fim laço

Os Comandos LABEL, GOTO e GOSUB, devem ser evitados. Um uso importante do GOTO é com o comando ON ERROR. Para obter mais detalhes sobre estes comandos, consulte a ajuda on-line.

9.4 Organização do Programa

No OOo Basic, um programa é organizado em procedimentos ( sub-rotinas ou funções ). O ponto de entrada da macro, procedimento principal, é da responsabilidade do programador. Sub-rotinas e funções podem ser intrínsicas (vem com o OOo Basic) ou definidas pelo usuário. Uma sub-rotina não retorna nenhum valor, já uma função retorna um valor, logo elas devem ser usadas com parte de uma expressão. Um procedimento pode ser chamado dentro de outros procedimentos de uma macro.

Qualquer bloco de código passível de reutilização na macro corrente ou noutra qualquer, deve ser implementado como um procedimento definido pelo usuário, este é o critério básico. Por exemplo, se numa macro, precisarmos determinar o menor dentre três valores mais de uma vez, devemos criar uma função própria para esta tarefa.

Comandos

Um comando é uma combinação de elementos do Basic, escrito de acordo com as regras de sintaxe da linguagem. Alguns podem ocorrer em qualquer parte do programa, outros não. Os comandos são os responsáveis pela funcionalidade dos procedimentos.



Normalmente um comando cabe numa só linha, caso contrário podemos usar o sublinhado, para indicar que o comando continua na próxima linha. O caractere de continuação não pode ser usado dentro de uma cadeia (string). Veja o exemplo:

Informe$ = “Esta é uma linha de comando que continua “ + _“na próxima linha”

Numa mesma linha, podemos escrever mais de um comando, usando o caractere dois pontos, como separador de comandos. Abaixo, temos três comandos de atribuição:

i = 0 : j = 1 : sinal = False

Sub-rotinas

Sub-rotinas devem ser definidas pelo comando SUB ... END SUB, da seguinte maneira:

SUB Nome_Da_Rotina ( Lista_De_Parâmetros )' ' Declaração de variáveis Locais ' Comandos da sub-rotina'END SUBA Lista_de_Parâmetros, são os valores, separados por vírgula, que a rotina recebe para executar o seu trabalho e devem conter a especificação de tipo. Por exemplo:

SUB MinhaSub (par1 As Integer, par2 As Double, par3 As String)Se um dos parâmetros for uma variável da macro o seu nome na lista da sub-rotina pode (e deve) ser diferente do nome da variável na macro.

Exemplo de sub-rotina que troca os valores de duas variáveis:

SUB TrocaValores ( valor1 As Double, valor2 As Double)' Dim temp As Double ' temp = valor1 valor1 = valor2 valor2 = temp ' Note que apesar de não retornar valores, as variáveis passadas ' como parâmetros foram alteradas e estas alterações serão ' visíveis na rotina que chamar TrocaValores'END SUB

Exemplo de sub-rotina que recebe três parâmetros e os imprime após formatação:

Sub ImprimePonto ( nomePto$, coordX#, coordY# ) Dim cadeia As string

' formata a cadeia, incluindo vírgulas, usa continuação de linha ( _ ) cadeia = Ltrim$(Rtrim$(nomePto)) + “, “ + Str$(coordX) + _ “, “ + Str$(coordY)



' imprime Print cadeia'End Sub

O comando EXIT SUB pode ser usado dentro de uma sub-rotina para abandoná-la imediatamente.

Funções

A definição de uma função é feita entre os comandos FUNCTION ... END FUNCTION, como abaixo:

FUNCTION NomeFuncao (ListaParametros) As TipoRetornado

' declaração das variáveis locais ' comandos da função

NomeFuncao = expressão_Retorno ' NÃO ESQUEÇA!

END FUNCTIONNote que uma função retorna o valor de uma expressão numa variável de nome igual ao nome da função.

O comando EXIT FUNCTION pode ser usado dentro de uma funçao para abandoná-la imediatamente.

Exemplo de uma função que calcula o volume de uma esfera, a partir do seu raio:

FUNCTION VolumeEsfera ( raio As Double ) As Double ' Dim diametro As Double ' diametro = 2 * raio VolumeEsfera = (PI / 6) * diametro ^ 3 ' NOTE: nome da função VolumeEsfera; nome da variável: VolumeEsfera ' END FUNCTION

Atenção, uma função não pode retornar uma MATRIZ.

Passagem de Parâmetros

A passagem de parâmetros para sub-rotinas e funções pode ser feita de duas maneiras, por referência (padrão) ou por valor. Quando um parâmetro (variável) é passado por referência, qualquer alteração em seu conteúdo será refletida na rotina chamadora. Se a passagem for por valor, as alterações na variável serão descartadas quando o procedimento terminar a sua execução e o valor original será preservado. Matrizes são passadas sempre por referência.



Para passar um parâmetro por valor, na definição do procedimento, use a palavra BYVAL, antes do nome do parâmetro, ou, se BYVAL omitida, coloque a variável entre parênteses, na chamada, veja abaixo:

SUB ImprimePonto (BYVAL cadeia$, X#, Y#)

cadeia = Ltrim$(Rtrim$(cadeia) + “, “ + Str$(X) + ”, “ + Str$(Y) Print cadeia ' a mudança em cadeia, será descartada no término da Sub

END SUB

Chamada de Procedimentos

A chamada a um procedimento depende do seu tipo, se sub-rotina ou função. Como uma sub-rotina não retorna valores, ela não precisa ser usada como parte de uma expressão. Já uma Função (sempre retorna um valor), deve ser usada numa expressão.

Formas de chamadas de sub-rotina:

' Usando o comando CALL com ou sem parêntesesCALL ImprimePonto (nomePonto, coordX, coordY) CALL ImprimePonto nomePonto, coordX, coordY' Sem o comando CALL, com ou sem parênteses.ImprimePonto (nomePonto, coordX, coordY)ImprimePonto nomePonto, coordX, coordYSe a sub-rotina não tiver parâmetros não é preciso usar os parênteses.

Formas de chamada de funções:

' chama a função areaCirculo e armazena o valor da area na variavel areCircareCirc = areaCirculo (raio)' chama 2 funcoes, areaCirculo ( ) e Str$ ( ) o valor retornado será atribuído a cadeiacadeia = Str$( areaCirculo ( raio ) )' chama 2 funcoes, Sqr ( ) e Distancia ( ) o valor retornado será atribuído a raizDistraizDist = Sqr ( Distancia ( x1, y1, x2, y2) )

Exemplo de chamadas de sub-rotinas e funções:

Sub chamadaProcedimentos Call UneCadeiasSub ("Meu ", "exemplo sub 1") Call UneCadeiasSub "Meu ", "exemplo sub 2" UneCadeiasSub ("Meu ", "exemplo sub 3") UneCadeiasSub "Meu ", "exemplo sub 4" ' Dim cad$ cad$ = UneCadeiasFunction$ ("Meu ", "exemplo function 1") MsgBox cad$ End Sub

Sub UneCadeiasSub ( cad1$, cad2$ )



MsgBox (cad1$ + cad2$) End Sub Function UneCadeiasFunction$ ( cad1$, cad2$ ) UneCadeiasFunction$ = cad1$ + cad2$ End Function

Neste exemplo, a sub-rotina principal é chamadaProcedimentos (é a rotina que deve ser executada), ela chama a Sub UneCadeiasSub e a função UneCadeiasFunction, ambas definidas pelo programador. As quatro formas de chamada da Sub UneCadeiasSub são equivalentes.

Modelo Geral de uma Macro

A organização geral de uma macro, pode seguir o modelo abaixo, no que for aplicável:

--------------------------------------------------------------------------------------------------------COMENTÁRIOS (Breve Descrição, Nome da Macro, Autor, Data, Chamada, Outros)DECLARAÇÃO DE VARIÁVEIS PÚBLICAS ( Public ... )DECLARAÇÃO DE VARIÁVEIS PRIVADAS (Private ... )DEFINIÇÃO DE CONSTANTES SIMBÓLICAS (Const ... )DEFINIÇÃO DO PROCEDIMENTO PRINCIPAL (Sub Main)DEFINIÇÃO DAS SUB-ROTINAS DA MACRO ( Sub ... End Sub )DEFINIÇÃO DAS FUNÇÕES DA MACRO ( Function ... End Function )--------------------------------------------------------------------------------------------------------

Neste apêndice, cobrimos apenas o básico sobre a linguagem Basic. Se você conseguiu chegar neste ponto, acredite que está apto a explorar sozinho outras potencialidades da linguagem.

O OpenOffice.org Basic tem uma grande quantidade de comandos e funções, todos muito bem documentados na Ajuda “on-line”, distribuída com o pacote. Estando no IDE Basic, basta pressionar a tecla F1 e um mundo de informações se apresentará à sua frente.


Versão 2 Mais informações

10 Mais informações

10.1 Na rede

OpenOffice.org : O lar do OpenOffice.org

http://www.openoffice.org

http://www.openoffice.org.br

Projeto de Documentação do OpenOffice.org:

http://documentation.openoffice.org

OpenOffice.org for Developers http://website.openoffice.org/developer

Este é o local para quem está interessado em desenvolvimento com o OpenOffice.org. Aqui, você encontra:

– OpenOffice.org 1.0.2 – Developer ' s Guide (~ 12 Mb )

– Manual de Referência da API do OpenOffice.org (~ 8 Mb )

– StarOffice 6.0 – Basic Programmer ' s Guide ( ~ 1 Mb )

– StarOffice 5.2 – Programmer ' s Tutorial (~ 1 Mb )

– Exemplos do Developer ' s Guide (~ 1 Mb )

OOoDocs.Org http://www.ooodocs.org

Documentação, fóruns ( inclusive sobre Macros) e notícias do OpenOffice.org.

OOOForum.Org http://www.oooforum.org

Fóruns do OpenOffice.org , inclusive sobre Macros e API.

OOExtras http://ooextras.sourceforge.net

Repositório de modelos, macros e assistentes para o OpenOffice.org. Baixe todas as macros e estude o código fonte para aprender mais.

Pitonyak.org www.pitonyak.org/

Andrew Pitonyak e seus colaboradores merecem a nossa gratidão. Esta página contém um excelente documento sobre macros e sobre a linguagem Basic. Consulte-a periodicamente.

EDV – Systeme Kienlein http://kienlein.com/pages/oo.html

Contém o DevGuide, com exemplos do Developer's Guide e o módulo Inspect uma excelente ferramenta para análise de objetos. Outro achado é o DbMonitor, um aplicativo OOo Basic completo, para acesso a Bancos de Dados.


http://kienlein.com/pages/oo.html

http://www.pitonyak.org/

http://ooextras.sourceforge.net/

http://www.oooforum.org/

http://www.ooodocs.org/

http://website.openoffice.org/developer

http://documentation.openoffice.org/

http://www.openoffice.org.br/

http://www.openoffice.org/

Mais informações Versão 2

10.2 Com o autor

Aceito solicitações para correções e inclusão de novos tópicos. Qualquer contribuição será muito bem recebida, neste caso, os créditos serão dos contribuidores.

Se você tiver alguma dúvida sobre o OpenOffice.org Basic, talvez eu possa lhe ajudar. Por favor, antes de um contato direto, poste a sua dúvida num fórum apropriado, assim você estará contribuindo para o aumento do “know-how” da comunidade.

Se você desejar entrar em contato comigo, envie uma mensagem para:

[email protected]

10.3 Histórico, alterações, ...

Por fazer:

1) Capítulo sobre Formulários;

2) Capítulo sobre Controles de Diálogos Personalizados;

3) Seção sobre Importar / Exportar Documentos, no capítulo 5;

4) Seções sobre “Listeners” e Eventos;

5) Seções sobre Internet e Correio Eletrônico.

Em 25/08/2003 - Liberação da versão 2 com as alterações abaixo:

1) Incluído o Capítulo sobre Banco de Dados;

2) Re-estruturação do capítulo Introdução a API do OpenOffice.org;

3) Incluído o Apêndice sobre a Linguagem Basic, sugestão de Gustavo Buzzatti Pacheco;

4) Incluída a seção Movimentando Dados, no capítulo do Calc;

5) Incluída a seção Dados de Fontes Externas, no capítulo do Calc;

6) Adicionada a seção Desenhos, no capítulo Documentos do Writer;

7) Adicionada a seção Seleção durante a execução da macro, em Documentos do Calc;

8) Correção na seção Compartilhando uma Macro, sugerida por Ismael Fanlo;

9) Correções diversas sugeridas por Gustavo Buzzatti Pacheco;

10) Mais links de informações e agradecimentos.

Em 06/07/2003: Publicação da Introdução na HomePage www.ioobasic.kit.net .

Em 02/07/2003: Publicação da versão 1, no site do OpenOffice.org – Projeto Brasil.

Em 02/04/2003: Início da Introdução ao OpenOffice.org Basic.


mailto:[email protected]

Versão 2 Créditos, Agradecimentos, Licença

11 Créditos, Agradecimentos, Licença

11.1 Créditos

Autor do layout gráfico do modelo: Mirto Silvio Busico <[email protected]>

Autor do texto explanatório do modelo: Gianluca Turconi <[email protected]>

11.2 Agradecimentos

A Sun Microsystems, Inc pelo apoio para a criação e desenvolvimento do OpenOffice.org.

A Sun Microsystems, Inc, mais uma vez, pela disponibilização da documentação sobre a API do OpenOffice.org, sem a qual este trabalho não seria possível.

A todos os voluntários que, com os seus trabalhos, contribuem para o crescimento do OpenOffice.org.

Aos coordenadores do OpenOffice.org – Projeto Brasil, pela publicação da Introdução, principalmente, a Gustavo Buzzatti Pacheco, pelo apoio e sugestões.

A Ismael Fanlo pela tradução da versão 1 deste documento para o Espanhol.

11.3 Licença

É permitida a cópia, distribuição e / ou modificação deste documento, sob os termos da GNU Free Documentation License, Version 1.1 ou uma versão posterior publicada pela Free Software Foundation. Uma cópia da licença acompanha este documento, consulte o arquivo FDL.TXT. Se você não recebeu uma cópia deste arquivo, por favor informe ao autor ou ao “webmaster” do site que disponibilizou este documento.

Copyright © 2003 Noelson Alves Duarte.




Documents

Introdução Ao OpenOffice.org Basic · rede, e se familiarizar com o Basic, antes de se aventurar no OOo Basic. É muito importante dominar os fundamentos de uma linguagem de programação