Introdução Ao OpenOffice.org Basic

Transcrição

1 Introdução Ao 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.

2

3 Versão 2 Índice 1 Macros OpenOffice.org Basic Introdução Criando a Primeira Macro Executando a Primeira Macro Compartilhando uma Macro Diálogos Personalizados Introdução Criando um Diálogo Manipulando Eventos do Diálogo Pilotos Automáticos Introdução Criando um Piloto Automático Manipulando Eventos do Piloto Automático Introdução a API do OpenOffice.org Visão geral Objetos Definindo objetos Criando um novo documento Trabalhando com Documentos Carregando Documentos Salvando Documentos Imprimindo Documentos Fechando Documentos Identificando os Documentos Abertos Documentos do Writer Introdução Editando texto Movendo-se pelo texto Formatando texto Formatando com estilo Obtendo o objeto selecionado Localizando objetos Busca e Substituição Inserindo objetos Tabelas Desenhos Documentos do Calc Introdução Planilhas Editando Navegando pelas Células Obtendo objetos selecionados Formatando Formatando Parágrafos e Caracteres...70 Mesclando Células Inserindo Bordas Introdução ao OpenOffice.org Basic 1

4 Versão 2 Formatação Numérica Formatação Condicional Busca e Substituição Ordenando Filtrando dados Inserindo Subtotais Gráficos Seleção durante a execução da macro Movimentando dados Dados de fontes externas Vínculos Importando dados de um banco de dados Banco de Dados Introdução Fontes de Dados Conexões Estrutura do Banco de Dados...99 Tabelas Chave Primária Índices Segurança Registros Criando um RowSet Navegando pelos registros Acessando os dados Alterando os dados Obtendo Metadados do RowSet Consultas Comandos SQL Comandos SQL Preparados Consultas Preparadas Vínculos Apêndice Linguagem Basic Primeiros Passos Elementos do Basic Palavras reservadas Regras para nomes Comentários Tipos de dados internos Declaração de variáveis Matrizes Escopo das variáveis Constantes simbólicas Expressões Fluxo de controle da execução Comando de decisão If... Then Comando de decisão Select Case Comando de repetição While... Wend Introdução ao OpenOffice.org Basic

5 Versão 2 Comando de repetição For... Next Comando de repetição Do... Loop Organização do Programa Comandos Sub-rotinas Funções Passagem de Parâmetros Chamada de Procedimentos Modelo Geral de uma Macro Mais informações Na rede Com o autor Histórico, alterações, Créditos, Agradecimentos, Licença Créditos Agradecimentos Licença Introdução ao OpenOffice.org Basic 3

6 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 online. 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 4 Introdução ao OpenOffice.org Basic

7 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 Introdução ao OpenOffice.org Basic 5

8 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 6 Introdução ao OpenOffice.org Basic

9 Versão 2 Macros OpenOffice.org 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: Introdução ao OpenOffice.org Basic 7

10 Macros OpenOffice.org Basic Versão 2 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. 8 Introdução ao OpenOffice.org Basic

11 Versão 2 Macros OpenOffice.org Basic 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. Introdução ao OpenOffice.org Basic 9

12 Macros OpenOffice.org Basic Versão 2 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 duploclique 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. 10 Introdução ao OpenOffice.org Basic

13 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. Introdução ao OpenOffice.org Basic 11

14 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. 12 Introdução ao OpenOffice.org Basic

15 Versão 2 Diálogos Personalizados Vamos trabalhar em nosso diálogo: Figura 7: Janela Propriedades 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. Introdução ao OpenOffice.org Basic 13

16 Diálogos Personalizados Versão 2 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 14 Introdução ao OpenOffice.org Basic

17 Versão 2 Diálogos Personalizados 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. Introdução ao OpenOffice.org Basic 15

18 Diálogos Personalizados Versão 2 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. 16 Introdução ao OpenOffice.org Basic

19 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. Introdução ao OpenOffice.org Basic 17

20 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). 18 Introdução ao OpenOffice.org Basic

21 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 = false End Sub Sub dlgvoltardialogo odialogo.model.step = 1 odialogo.model.commandbutton3.enabled = false odialogo.model.commandbutton4.enabled = true End 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 Introdução ao OpenOffice.org Basic 19

22 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. 20 Introdução ao OpenOffice.org Basic

23 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ário com.sun.star.beans - serviços para acesso a propriedades com.sun.star.container - interfaces para coleções e recipientes com.sun.star.document - serviços para documentos do office com.sun.star.drawing - serviços para desenho com.sun.star.text - serviços para documentos texto com.sun.star.sdb - serviços para banco de dados com.sun.star.sheet - serviços para planilhas com.sun.star.util - serviços de utilidade diversa Como 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ódulo Interfaces - relação de interfaces do módulo Structs - relação de est ruturas do módulo Exceptions - relação de exceções do módulo Enums - relação de enumerações do módulo Constant Groups - relação de grupos de constantes do módulo Um 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 ao OpenOffice.org Basic 21

24 Introdução a API do OpenOffice.org Versão 2 Struct < com.sun.star.awt.size > Width - valor do tipo longo (Long), especificando a largura Height - 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 simples Dim vetortam (2) As New com.sun.star.awt.size declara um vetor para 3 elementos Dim vtam ( ) As New com.sun.star.awt.size declara um vetor vazio O 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 vtamanho vtamanho.width = 2000 vtamanho.height = 1000 ou, ainda naltura = vtamanho.height acesso aos campos de um vetor de estrutura vetortam(0).width = 5000 vetortam(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ão OK - comporta-se como um botão Ok CANCEL - comporta-se como um botão Cancelar HELP - comporta-se como um botão Ajuda Normalmente, 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 22 Introdução ao OpenOffice.org Basic

25 Versão 2 Introdução a API do OpenOffice.org 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 Boolean PageStyle - 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 planilha createcursorbyrange - cria um cursor para uma extensão de células Um 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 planilha bvisivel = oplanilha1.isvisible atribui a bvisivel o valor da propriedade IsVisible Introdução ao OpenOffice.org Basic 23

26 Introdução a API do OpenOffice.org Versão 2 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. 24 Introdução ao OpenOffice.org Basic

27 Versão 2 Introdução a API do OpenOffice.org 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 subrotina, 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_SupportedInterfaces retorna as interfaces suportadas pelo objeto Dbg_Properties retorna as propriedades do objeto Dbg_Methods retorna 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_SupportedInterfaces End Sub A interface com.sun.star.lang.xserviceinfo possui os métodos abaixo, úteis para inspeção de serviços: getimplementationname ( ) As String retorna o nome de implementação do serviço supportsservice (snome As String ) As Boolean retorna True se o serviço snome for suportado getsupportedservicenames ( ) As String () Introdução ao OpenOffice.org Basic 25

28 Introdução a API do OpenOffice.org Versão 2 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_properties End 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") 26 Introdução ao OpenOffice.org Basic

29 Versão 2 Introdução a API do OpenOffice.org 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. Introdução ao OpenOffice.org Basic 27

30 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_arquivo Para 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 private:factory/swriter private:factory/scalc private:factory/sdraw private:factory/simpress Descrição Cria um novo documento do Writer Cria um novo documento do Calc Cria um novo documento do Draw 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): 28 Introdução ao OpenOffice.org Basic

31 Versão 2 Trabalhando com Documentos Propriedade Tipo Descrição AsTemplate 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 Overwrite Boolean Se True, o documento não será exibido na interface gráfica 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. Introdução ao OpenOffice.org Basic 29

32 Trabalhando com Documentos Versão 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 AQUI da 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 30 Introdução ao OpenOffice.org Basic

33 Versão 2 Trabalhando com Documentos 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 Boolean Retorna True se o recurso foi modificado, senão retorna False. haslocation ( ) As Boolean Retorna True se o arquivo já existe (foi gravado), senão retorna False. GetLocation ( ) As String Retorna uma String com a URL do recurso. isreadonly ( ) As Boolean Retorna 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: Name Propriedade PaperOrientation Descrição Uma cadeia (String) com o nome da fila de impressão Contém a orientação do papel Introdução ao OpenOffice.org Basic 31

34 Trabalhando com Documentos Versão 2 Propriedade PaperFormat PaperSize IsBusy CanSetPaperOrientation CanSetPaperFormat Descrição Especifica um tamanho de papel padrão ou definido pelo usuário Especifica o tamanho do papel em 1/100 mm True se a impressora estiver ocupada; False senão True se a impressora permite mudar a orientação do papel 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).value End 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. 32 Introdução ao OpenOffice.org Basic

35 Versão 2 Trabalhando com Documentos 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 CopyCount FileName Collate Pages Descrição ( Int ) Especifica o número de cópias a imprimir Cadeia com o nome de um arquivo para a impressão 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 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() ) Introdução ao OpenOffice.org Basic 33

36 Trabalhando com Documentos Versão 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() 34 Introdução ao OpenOffice.org Basic

37 Versão 2 Trabalhando com Documentos 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. Introdução ao OpenOffice.org Basic 35

38 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 " 36 Introdução ao OpenOffice.org Basic

39 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 String retorna 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. Introdução ao OpenOffice.org Basic 37

40 Documentos do Writer Versão 2 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 Boolean move 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 Boolean gotoendofword (bexpande As Boolean) As Boolean gotostartofword (bexpande As Boolean) As Boolean 38 Introdução ao OpenOffice.org Basic

41 Versão 2 Documentos do Writer isstartofword ( ) As Boolean isendofword ( ) As Boolean b) Métodos de XSentenceCursor: gotonextsentence (Expande As Boolean) As Boolean gotoprevioussentence (bexpande As Boolean) As Boolean gotostartofsentence (bexpande As Boolean) As Boolean gotoendofsentence (bexpande As Boolean) As Boolean isstartofsentence ( ) As Boolean isendofsentence ( ) As Boolean c) Métodos de XParagraphCursor: gotostartofparagraph (bexpande As Boolean) As Boolean gotoendofparagraph (bexpande As Boolean) As Boolean gotonextparagraph (bexpande As Boolean) As Boolean gotopreviousparagraph (bexpande As Boolean) As Boolean isstartofparagraph ( ) As Boolean isendofparagraph ( ) 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_PARAGRAP H 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 Introdução ao OpenOffice.org Basic 39

42 Documentos do Writer Versão 2 End Sub 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) 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. 40 Introdução ao OpenOffice.org Basic

43 Versão 2 Documentos do Writer 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 CharFontName CharFontStyleNa me Descrição Especifica o nome do estilo da fonte 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: Introdução ao OpenOffice.org Basic 41

44 Documentos do Writer Versão 2 Propriedade ParaAdjust ParaBackColor ParaLastLineAdju st Descrição Define o tipo de ajuste (com.sun.star.style.paragraphadjust) Contém a cor de fundo, é opcional 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 ParaBottomMargi n ParaStyleName Define a margem superior do parágrafo em 1/100 mm (As Long) Define a margem inferior do parágrafo em 1/100 mm (As Long) 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 ParaFirstLineInde nt ParaVertAlignmen t Valor com a distância da borda ao objeto (As Long) Valor longo com a identação da primeira linha, é opcional 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. 42 Introdução ao OpenOffice.org Basic

45 Versão 2 Documentos do Writer 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 Introdução ao OpenOffice.org Basic 43

46 Documentos do Writer Versão 2 ParagraphStyles FrameStyles PageStyles NumberingStyles - estilos de parágrafos - estilos de molduras - estilos de páginas - 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 Variant getelementnames ( ) As astrings ( ) hasbyname ( snome As String ) As Boolean con.sun.star.container.xindexacess getcount ( ) As Long getbyindex ( 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 BackColor LeftMargin RightMargin TopMargin BottomMargin IsLandscape Descrição Valor Long da cor de fundo da página Valor Long da margem esquerda em 1/100 mm Valor Long da margem direita em 1/100 mm Valor Long da margem superior em 1/100 mm Valor Long da margem inferior em 1/100 mm Determina se o formato da página é paisagem (True / False) 44 Introdução ao OpenOffice.org Basic

47 Versão 2 Documentos do Writer PageStyleLayout Determina o layout da página (com.sun.star.style.pagestylelayout) Size Width Height Valores Long definindo o tamanho do papel (Size.Width e Size.Height) Valor Long definindo a largura da página em 1/100 mm 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 HeaderRightMarg in HeaderIsOn FooterLeftMargin FooterRightMargi n FooterIsOn Valor Long definindo a margem direita do cabeçalho em 1/100 mm Determina se o cabeçalho está ativo na página (True / False) Valor Long definindo a margem esquerda do rodapé em 1/100 mm Valor Long definindo a margem direita do rodapé em 1/100 mm 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 Introdução ao OpenOffice.org Basic 45

48 Documentos do Writer Versão 2 End Sub 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) 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.stylesfamilies no 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 46 Introdução ao OpenOffice.org Basic

49 Versão 2 Documentos do Writer 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 Object O objeto retornado é do tipo com.sun.star.uno.xinterface e depende do conteúdo da seleção. Conteúdo da seleção Texto Células de tabela Caixa de texto Gráfico Desenho Objeto retornado Um ou mais objetos apontando para TextRange Um objeto apontando para um cursor de tabela Um objeto apontando para uma caixa de texto Um objeto apontando para um gráfico 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: Introdução ao OpenOffice.org Basic 47

50 Documentos do Writer Versão 2 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.count End 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 Boolean se 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 String retorna o nome da implementação do objeto getname ( ) As String retorna o nome do objeto, se o mesmo for nomeado, caso de gráficos e tabelas. 48 Introdução ao OpenOffice.org Basic

51 Versão 2 Documentos do Writer 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 Boolean retorna 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 Long retorna 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 Boolean retorna True se ainda existem elementos no recipiente Introdução ao OpenOffice.org Basic 49

52 Documentos do Writer Versão 2 nextelement ( ) As Variant retorna 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. 50 Introdução ao OpenOffice.org Basic

53 Versão 2 Documentos do Writer 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 String obtém a cadeia de busca setsearchstring ( scadeia As String ) define a cadeia de busca Eis algumas de suas propriedades: Propriedade SearchBackwards SearchCaseSensitive SearchWords SearchStyles Descrição Se True busca para o início do documento Se True considera maiúsculas / minúsculas Se True busca palavras completas 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 subrotina. Sub buscatodas Dim odoc As Object Dim odescbusca As Object odoc = ThisComponent Introdução ao OpenOffice.org Basic 51

54 Documentos do Writer Versão 2 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 String obté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 52 Introdução ao OpenOffice.org Basic

55 Versão 2 Documentos do Writer 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. Introdução ao OpenOffice.org Basic 53

56 Documentos do Writer Versão 2 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 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 LeftMargin RightMargin Split TableBorder TableColumnSeparator s Descrição Contém a margem esquerda da tabela, valor Long Contém a margem direita da tabela, valor Long Um valor False impede a divisão da tabela em duas páginas Contém a descrição da borda da tabela Contém a descrição dos separadores de colunas da tabela 54 Introdução ao OpenOffice.org Basic

57 Versão 2 Documentos do Writer 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 Type haselements ( ) As Boolean getbyindex ( ) As Variant getcount ( ) As Long A interface XTextTableCursor, retornada pelo método createcursorbycellname, acima, provê os métodos: getrangename ( ) As String Retorna 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 Boolean goright ( nquant As Integer, bexpande As Boolean ) As Boolean goup ( nquant As Integer, bexpande As Boolean ) As Boolean godown ( nquant As Integer, bexpande As Boolean ) As Boolean gotostart ( 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 Boolean Desloca o cursor para a célula nomeada no parâmetro. mergerange ( ) As Boolean splitrange ( nquant As Integer, bhoriz As Boolean ) As Boolean Mé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 Introdução ao OpenOffice.org Basic 55

58 Documentos do Writer Versão 2 CellBackColor HoriJustify VertJustify IsTextWrapped Orientation RotateAngle TableBorder TopBorder BottomBorder LeftBorder RightBorder NumberFormat CellProtection Valor Long com a cor de fundo da célula Alinhamento horizontal do conteúdo da célula (enum CellHoriJustify) Alinhamento vertical do conteúdo da célula (enum CellVertJustify) Se True, o texto muda de linha automaticamente Orientação do conteúdo da célula (enum CellOrientation) Define a rotação do conteúdo da célula (em 1/100 graus) Descreve a borda das células (struct TableBorde) Descreve a borda superior de cada célula (struct BorderLine) Descreve a borda inferior de cada célula (struct BorderLine) Descreve a borda esquerda de cada célula (struct BorderLine) Descreve a borda direita de cada célula (struct BorderLine) Índice do formato numérico usado nas células (serviço NumberFormatter) 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 Double setvalue ( 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 Long retorna 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 String setname ( 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 56 Introdução ao OpenOffice.org Basic

59 Versão 2 Documentos do Writer 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 IsCaseSensitive Descrição 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ção SortFields 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 Introdução ao OpenOffice.org Basic 57

60 Documentos do Writer Versão 2 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. 58 Introdução ao OpenOffice.org Basic

61 Versão 2 Documentos do Writer 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 Introdução ao OpenOffice.org Basic 59

62 Documentos do Writer Versão 2 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 If End 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 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 AnchorType HoriOrient VertOrient LeftMargin RightMargin TopMargin BottomMagin Descrição Tipo da âncora Orientação horizontal Orientação vertical Margem esquerda Margem direita Margem superior 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 > ) 60 Introdução ao OpenOffice.org Basic

63 Versão 2 Documentos do Writer 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 Introdução ao OpenOffice.org Basic 61

64 Documentos do Writer Versão 2 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 = 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 = 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) 62 Introdução ao OpenOffice.org Basic

65 Versão 2 Documentos do Writer 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 - 1 oshape = opage.getbyindex ( i ) obtem nome se definido na criação smsg = smsg + oshape.getname() + chr$(10) smsg = smsg + oshape.getshapetype() + chr$(10) Next i MsgBox 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. Introdução ao OpenOffice.org Basic 63

66 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. 64 Introdução ao OpenOffice.org Basic

67 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. Introdução ao OpenOffice.org Basic 65

68 Documentos do Calc Versão 2 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 Double setvalue ( 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. 66 Introdução ao OpenOffice.org Basic

69 Versão 2 Documentos do Calc 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) Introdução ao OpenOffice.org Basic 67

70 Documentos do Calc Versão 2 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 Position Size FormulaLocal FormulaResultType ConditionalFormat ConditionalFormatLoc al Validation ValidationLocal Descrição Somente leitura, posição da célula na planilha Somente leitura, tamanho da célula em 1/100 mm Cadeia com o nome local da fórmula Somente leitura, tipo do resultado de uma fórmula Definições de formatação condicional da célula Definições locais de formatação condicional da célula Definições de validação da célula 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 68 Introdução ao OpenOffice.org Basic

71 Versão 2 Documentos do Calc 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) Introdução ao OpenOffice.org Basic 69

72 Documentos do Calc Versão 2 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. 70 Introdução ao OpenOffice.org Basic

73 Versão 2 Documentos do Calc 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 Boolean se 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" Introdução ao OpenOffice.org Basic 71

74 Documentos do Calc Versão 2 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 Height OptimalHeight IsVisible IsStartOfNewPage Descrição Define a altura da linha em 1/100 mm Se True, ajusta automaticamente a altura da linha Se True, a linha será exibida 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 Width OptimalWidth IsVisible IsStartOfNewPage Descrição Define a largura da coluna em 1/100 mm Se True, ajusta automaticamente a largura da coluna Se True, a coluna será exibida 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 72 Introdução ao OpenOffice.org Basic

75 Versão 2 Documentos do Calc com.sun.star.table.tableborder com.sun.star.table.borderline O 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 Boolean Retorna 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 TableBorder TopBorder BottomBorder RightBorder Descrição Define a borda de uma célula ou extensão de células Define a borda superior de cada célula da extensão Define a borda inferior de cada célula da extensão Define a borda direita de cada célula da extensão Introdução ao OpenOffice.org Basic 73

76 Documentos do Calc Versão 2 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 > 74 Introdução ao OpenOffice.org Basic

77 Versão 2 Documentos do Calc 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 Long addnew ( 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 Introdução ao OpenOffice.org Basic 75

78 Documentos do Calc Versão 2 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 conditionalformatlocal - define condições para formatação condicional - 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: 76 Introdução ao OpenOffice.org Basic

79 Versão 2 Documentos do Calc 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 String setsearchstring ( scadeia As String ) Eis algumas de suas propriedades: Propriedade SearchBackwards SearchCaseSensitive Descrição Se True, busca para o início do documento Se True, considera maiúsculas / minúsculas Introdução ao OpenOffice.org Basic 77

80 Documentos do Calc Versão 2 Propriedade SearchWords SearchStyles Descrição 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. 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 String setreplacestring ( 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 78 Introdução ao OpenOffice.org Basic

81 Versão 2 Documentos do Calc 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 IsCaseSensitive SortAscending SortColumns Descrição Se True, considera maiúsculas / minúsculas Define a ordem da ordenação 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ção SortFields 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 Introdução ao OpenOffice.org Basic 79

82 Documentos do Calc Versão 2 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 SkipDuplicates - se True, destingue maiúsculas e minúsculas - setrue, as entradas duplicadas serão excluídas 80 Introdução ao OpenOffice.org Basic

83 Versão 2 Documentos do Calc Orientation - filtra por Linhas ou Colunas ( TableOrientation ) ContainsHeader - a primeira linha ou coluna é um cabeçalho CopyOutputData - 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ção Operator - operador condicional ( FilterOperator ) IsNumeric - se True, o valor do campo (Field) é numérico NumericValue - valor do campo, usar se IsNumeric for True StringValue - 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()) Introdução ao OpenOffice.org Basic 81

84 Documentos do Calc Versão 2 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 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 subtotal IsCaseSensitive - considera letras maiúsculas / minúsculas EnableUserSortList - se True permite a definição de uma lista para ordenação UserSortListIndex - a lista para ordenação, se EnableUserSortList for True EnableSort - define se o conteúdo dos campos serão ordenados SortAscending - 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) 82 Introdução ao OpenOffice.org Basic

85 Versão 2 Documentos do Calc 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 Function - índice da coluna a subtotalizar - 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 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. Introdução ao OpenOffice.org Basic 83

86 Documentos do Calc Versão 2 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 oarea oext btitcol btitlin - o nome do gráfico - a área (retângulo) aonde o gráfico será plotado - a extensão de células com os dados - se True, os dados da linha superior serão usados na legenda do gráfico - 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 Boolean sethascolumnheaders ( btitulocoluna As Boolean ) gethasrowheaders ( ) As Boolean sethasrowheaders ( 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 HasSubTitle HasLegend - Se True, exibe o título principal - Se True, exibe o subtítulo - 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: 84 Introdução ao OpenOffice.org Basic

87 Versão 2 Documentos do Calc 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 DataCaption - define se a série de dados é por linhas ou colunas - 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 Introdução ao OpenOffice.org Basic 85

88 Documentos do Calc Versão 2 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 = oret.height = 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" 86 Introdução ao OpenOffice.org Basic

89 Versão 2 Documentos do Calc 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 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 $Planilha1.$a$1:$b$5 Title CloseOnMouseRelease Valor inicial para a seleção, por ex: Título do diálogo da seleção 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 ( ) Introdução ao OpenOffice.org Basic 87

90 Documentos do Calc Versão 2 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 String Public bselecao As Boolean Sub Main Dim odoc As Object Dim odocview As Object 88 Introdução ao OpenOffice.org Basic

91 Versão 2 Documentos do Calc 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 = True End Sub aborted ( ) Sub olist_aborted ( oevent ) bselecao = True End Sub Sub olist_disposing () implementação mínima End Sub Introdução ao OpenOffice.org Basic 89

92 Documentos do Calc Versão 2 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 ) Sub olist_aborted ( oevent ) Sub olist_disposing ( ) - corresponde ao método done ( ) da interface - corresponde ao método aborted ( ) da interface - 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 ( ) 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 DOWN RIGHT - nenhuma célula será movida - as células abaixo das células inseridas são movidas para baixo - as células à direita das células inseridas são movidas para a direita 90 Introdução ao OpenOffice.org Basic

93 Versão 2 Documentos do Calc ROWS - as linhas abaixo das células inseridas são movidas para baixo COLUMNS - as colunas à direita das células inseridas são movidas para a direita estas 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á movida UP - as células abaixo das células apagadas são movidas para cima LEFT - as células à direita das células apagadas são movidas para a esquerda ROWS - as linhas abaixo das células apagadas são movidas para cima COLUMNS - as colunas à direita das células apagadas são movidas para a esquerda estas 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 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 Introdução ao OpenOffice.org Basic 91

94 Documentos do Calc Versão 2 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 documento AreaLinks - contém a coleção de vínculos de áreas no documento DDELinks - contém a coleção de vínculos DDE do documento Estas 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 String setlinkurl ( surl As String ) obtém ou define a URL do recurso ( o documento vinculado ) getlinksheetname ( ) As String setlinksheetname ( 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 NORMAL VALUE - sem vínculo - copia os valores e as fórmulas - 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 XML MS Excel 97 - documentos do Excel 97/2000/XP MS Excel 95 - documentos do Excel 5.0 / 95 Para estes filtros, podemos passar uma cadeia vazia como opção do filtro. Vejamos um exemplo: Sub vinculoplanilha 92 Introdução ao OpenOffice.org Basic

95 Versão 2 Documentos do Calc 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" Introdução ao OpenOffice.org Basic 93

96 Documentos do Calc Versão 2 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 SourceType DatabaseName SourceObject Descrição Tipo da fonte (com.sun.star.sheet.dataimportmode) Cadeia com o nome da fonte de dados registrada no OOo 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 94 Introdução ao OpenOffice.org Basic

97 Versão 2 Documentos do Calc SQL TABLE QUERY - um comando SQL será passado para SourceObject - o nome de uma tabela será passado para SourceObject - 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. Introdução ao OpenOffice.org Basic 95

98 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 96 Introdução ao OpenOffice.org Basic

99 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: Introdução ao OpenOffice.org Basic 97

100 Banco de Dados Versão 2 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: Name URL User Propriedade Password Nome da fonte de dados Descrição URL do banco de dados (sdbc:subprotocolo:subname ou jdbc...) Nome de login do usuário 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 98 Introdução ao OpenOffice.org Basic

101 Versão 2 Banco de Dados 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 subrotina 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" Introdução ao OpenOffice.org Basic 99

102 Banco de Dados Versão 2 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 Long obté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 100 Introdução ao OpenOffice.org Basic

103 Versão 2 Banco de Dados commit ( ) rollback ( ) isclosed ( ) As Boolean getmetadata ( ) 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 String getdatabaseproductname ( ) As String getdrivername ( ) As String gettables ( ) As < com.sun.star.sdbc.xresultset > getcolumns ( ) As < com.sun.star.sdbc.xresultset > getnumericfunctions ( ) As String getstringfunctions ( ) As String getsystemfunctions ( ) As String gettimedatefunctions ( ) As String supportsexpressionsinorderby ( ) As Boolean supportsgroupby ( ) As Boolean supportsouterjoins ( ) As Boolean supportsstoredprocedures ( ) 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 Introdução ao OpenOffice.org Basic 101

104 Banco de Dados Versão 2 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: Privileges Propriedade Descrição Valor longo contendo os privilégios da tabela 102 Introdução ao OpenOffice.org Basic

105 Versão 2 Banco de Dados Name CatalogName SchemaName Description Type Cadeia com o nome da tabela Cadeia com o nome do catálogo Cadeia com o nome do esquema Cadeia com descrição adicional 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 Filter ApplyFilter Order Descrição Cadeia com um filtro de dados adicional Se True, aplica o filtro 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: Name Propriedade O nome da coluna Descrição Type O tipo de dado da coluna ( com.sun.star.sdbc.datatype ) Precision O número de dígitos da coluna ( largura ) Scale IsAutoIncrement IsCurrency Description Número de dígitos à direita do ponto decimal Se True, a coluna é incrementada automaticamente Se True, o valor representa uma moeda 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. Introdução ao OpenOffice.org Basic 103

106 Banco de Dados Versão 2 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 104 Introdução ao OpenOffice.org Basic

107 Versão 2 Banco de Dados 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 Name CatalogName SchemaName Description Descrição Nome do objeto a ser criado (do serviço Descriptor) Cadeia com o nome do catálogo Cadeia com o nome do esquema Cadeia com descrição adicional O serviço com.sun.star.sdbcx.columndescriptor tem várias propriedades, seguem algumas: Name Propriedade O nome da coluna Descrição Type O tipo de dado da coluna ( com.sun.star.sdbc.datatype ) Precision O número de dígitos da coluna ( largura ) Scale IsAutoIncrement Número de dígitos à direita do ponto decimal 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: Introdução ao OpenOffice.org Basic 105

108 Banco de Dados Versão 2 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 106 Introdução ao OpenOffice.org Basic

109 Versão 2 Banco de Dados 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 Name Type ReferencedTable UpdateRule Descrição Nome da chave Tipo da chave (PRIMARY, UNIQUE, FOREIGN) Nome da tabela, somente para chaves externas Regra de atualização, somente para chaves externas Introdução ao OpenOffice.org Basic 107

110 Banco de Dados Versão 2 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ção Name 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. 108 Introdução ao OpenOffice.org Basic

111 Versão 2 Banco de Dados Í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 Name Catalog IsUnique IsPrimaryKey IsClustered Descrição Nome do índice Nome do catálogo do índice Se True, não aceita valores repetidos na coluna Se True, o índice é usado como chave primária 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ção Name Nome do índice ( de Descriptor ) Catalog IsUnique IsClustered Nome do catálogo do índice Se True, não aceita valores repetidos na coluna 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ção Name 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") Introdução ao OpenOffice.org Basic 109

112 Banco de Dados Versão 2 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. 110 Introdução ao OpenOffice.org Basic

113 Versão 2 Banco de Dados 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 objeto getgrantableprivileges ( ) - obtém os privilégios, que podem ser concedidos a outros grantprivileges ( ) - concede os privilégios revokeprivileges ( ) - 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. Introdução ao OpenOffice.org Basic 111

114 Banco de Dados Versão 2 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 ActiveConnection DataSourceName Command Descrição Um objeto Conexão gerada por uma fonte ou URL Cadeia com o nome da fonte de dados É o comando a ser executado, depende de CommandType CommandType O tipo de comando, definido em < sdb.commandtype > Filter Order RowCount IsRowCountFinal IsNew O nome de um filtro para o resultado do comando O nome de uma ordenação para o resultado do comando Número de registros acessados na base de dados Se True, indica que todos os registros foram contados Se True, indica que o registro será inserido no banco de dados IsModified Se True, indica que o registro corrente foi alterado As quatro últimas propriedades são apenas para leitura. O grupo < com.sun.star.sdb.commandtype > define as seguintes constantes: TABLE QUERY COMMAND - indica que Command receberá o nome de uma tabela - indica que Command receberá o nome de uma consulta - 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: MaxRows User Propriedade Descrição Tenta obter o número máximo de linhas Nome do usuário para a conexão 112 Introdução ao OpenOffice.org Basic

115 Versão 2 Banco de Dados 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 Introdução ao OpenOffice.org Basic 113

116 Banco de Dados Versão 2 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 Boolean first ( ) As Boolean last ( ) As Boolean previous ( ) As Boolean beforefirst ( ) As Boolean afterlast ( ) As Boolean movimenta o cursor de linha, retorna True em caso de sucesso. isfirst ( ) As Boolean islast ( ) As Boolean isbeforefirst ( ) As Boolean isafterlast ( ) As Boolean verifica a posição do cursor no ResultSet getrow ( ) As Long retorna a posição corrente do cursor no ResultSet absolute ( nlinha As Long ) As Boolean move o cursor para a linha nlinha, retorna True se bem sucedido relative ( nlinhas As Long ) As Boolean move 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 Boolean rowinserted ( ) As Boolean rowdeleted ( ) As Boolean verifica 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 String getboolean ( ncoluna As Long ) As Boolean getint ( ncoluna As Long ) As Integer 114 Introdução ao OpenOffice.org Basic

117 Versão 2 Banco de Dados getfloat ( ncoluna As Long ) As Single getdouble ( ncoluna As Long ) As Double getdate ( 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 Boolean se 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. Introdução ao OpenOffice.org Basic 115

118 Banco de Dados Versão 2 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") 116 Introdução ao OpenOffice.org Basic

119 Versão 2 Banco de Dados 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 Introdução ao OpenOffice.org Basic 117

120 Banco de Dados Versão 2 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 Long retorna o número de colunas do ResultSet. getcolumnname ( ncoluna As Long ) As String retorna o nome da coluna ncoluna. getprecision ( ncoluna As Long ) As Long retorna a precisão da coluna ncoluna. getscale ( ncoluna As Long ) As Long retorna a quantidade de dígitos após o separador decimal. gettablename ( ncoluna As Long ) As String retorna o nome da tabela da coluna ncoluna, útil em resultados com mais de uma tabela. getcolumntype ( ncoluna As Long ) As Long retorna o tipo SQL da coluna ncoluna. 118 Introdução ao OpenOffice.org Basic

121 Versão 2 Banco de Dados 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 Name Command EscapeProcessing Descrição O nome da definição (somente leitura) O comando da consulta, normalmente um comando SELECT 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 Introdução ao OpenOffice.org Basic 119

122 Banco de Dados Versão 2 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) + " - " + _ 120 Introdução ao OpenOffice.org Basic

123 Versão 2 Banco de Dados 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. Introdução ao OpenOffice.org Basic 121

124 Banco de Dados Versão 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ção CursorName - nome do cursor SQL, depende do banco de dados ResultSetConcurrency - 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 atualizado UPDATABLE - pode ser atualizado Os valores abaixo são definidos em com.sun.star.sdbc.resultsettype: FORWARD_ONLY SCROLL_INSENSITIVE SCROLL_SENSITIVE - o cursor se move para adiante - ambas as direções, insensível a mudanças - 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 Long executa um comando SQL de atualização, para comandos DDL retorna zero. execute ( scmdsql As String ) As Boolean executa 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 122 Introdução ao OpenOffice.org Basic

125 Versão 2 Banco de Dados retorna o contador de resultados getmoreresults ( ) As Boolean move 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. Introdução ao OpenOffice.org Basic 123

126 Banco de Dados Versão 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 Long execute ( ) As Boolean getconnection ( ) 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 124 Introdução ao OpenOffice.org Basic

127 Versão 2 Banco de Dados 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 Introdução ao OpenOffice.org Basic 125

128 Banco de Dados Versão 2 QUERY COMMAND - indica que scomando receberá o nome de uma consulta - 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 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: 126 Introdução ao OpenOffice.org Basic

129 Versão 2 Banco de Dados 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. Introdução ao OpenOffice.org Basic 127

130 Apêndice Linguagem Basic Versão 2 9 Apêndice Linguagem Basic A linguagem BASIC (Beginners 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 Sub Se 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 Dim ssauda As String Dim shora As Integer variável para guardar o nome variável para guardar a saudação 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. 128 Introdução ao OpenOffice.org Basic

131 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 Main Esta 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 subrotina. 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 Estas 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 ) Then Aqui, 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). Else Senã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 Introdução ao OpenOffice.org Basic 129

132 Apêndice Linguagem Basic Versão 2 Esta linha indica o final do comando de decisão IF... THEN... ELSE... END IF. MsgBox ssauda + snome Esta 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 Sub Esta 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 Basic CALL - comando do Basic SUB - comando do Basic FOR - parte de um comando do Basic NEXT - parte de um comando do Basic EXIT - parte de comandos do Basic WHILE - parte de comandos do Basic DO - parte de comandos do Basic STR$ - função do Basic TRIM$ - função do Basic SQR - função do Basic AND - operador do Basic OR - operador do Basic PI - constante definida pelo Basic O 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, subrotinas e funções: 130 Introdução ao OpenOffice.org Basic

133 Versão 2 Apêndice Linguagem Basic 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 DIM coord_y As Double variável para guardar a coordenada X do ponto variável para guardar a coordenada Y do ponto Tipos de dados internos Inteiros ( INTEGER ) Um inteiro pode conter um valor na faixa de a Inteiros Longos ( LONG ) Um inteiro longo pode conter um valor na faixa de a Ponto flutuante simples ( SINGLE ) Valores de precisão simples podem variar de E38 a E-45, para números positivos ou negativos. Ponto flutuante duplo ( DOUBLE ) Os valores de dupla precisão variam na faixa de E308 a E-324, para valores negativos ou positivos. Moeda ( CURRENCY ) Os valores deste tipo variam de ,5808 até ,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. Introdução ao OpenOffice.org Basic 131

134 Apêndice Linguagem Basic Versão 2 Cadeias de caracteres ( STRING ) Uma cadeia pode conter até 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_dado Ou: DIM nome_da_variavel seguido do caractere indicador do tipo de dado nome_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 UmLongo& = MeuNome$ = JOSÉ DE ANDRADE UmRealSimples! = UmRealDuplo# = coordene * sin(30) declara um inteiro declara um inteiro longo declara uma cadeia declara um real simples 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 132 Introdução ao OpenOffice.org Basic

135 Versão 2 Apêndice Linguagem Basic dimensão. Os índices são valores inteiros (negativos ou positivos). Até 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 desconhecido Após conhecer o número de pontos, podemos redimensionar o vetor com REDIM: NumeroPontos = 100 Redim 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 subrotinas 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 Public estilolinha As Integer visível por todas as macros visível apenas nesta macro Sub trocavalor(valor1%, valor2%) Dim temp% temp é visível apenas em trocavalor... outros comandos Introdução ao OpenOffice.org Basic 133

136 Apêndice Linguagem Basic Versão 2 End Sub Sub Main Dim var1 As Integer pesolinha% = 2... outros comandos End Sub visível apenas pela Sub Main visível apenas pela Sub Main 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# = 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 valor# = valor1 * BASE_NATURAL declara vetor com 1001 elementos 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 134 Introdução ao OpenOffice.org Basic

137 Versão 2 Apêndice Linguagem Basic 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 2 Exemplos: 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: Introdução ao OpenOffice.org Basic 135

138 Apêndice Linguagem Basic Versão 2 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 Operandos NOT 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 136 Introdução ao OpenOffice.org Basic

139 Versão 2 Apêndice Linguagem Basic 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 ordem Para forçar a avaliação de uma expressão podemos, sempre, usar parênteses (maior precedência). Exemplo: valor1 = / 3 após avaliação valor1 = 8 valor2 = ( ) / 3 após avaliação valor2 = 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 Se Segunda 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 Introdução ao OpenOffice.org Basic 137

140 Apêndice Linguagem Basic Versão 2 Else Execute este bloco de comandos End If Fim Se Terceira 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 comandos ElseIf (expressão) Then Execute este bloco de comandos Else Execute este bloco de comandos End 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 maior = a Else maior = b End If se a for > que b, então armazene o valor de a na variavel maior senão armazene o valor de b na variavel maior 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 comandos End 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. 138 Introdução ao OpenOffice.org Basic

141 Versão 2 Apêndice Linguagem Basic 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 enquanto Este 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 Introdução ao OpenOffice.org Basic 139

142 Apêndice Linguagem Basic Versão 2 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 é opcional O 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 140 Introdução ao OpenOffice.org Basic

143 Versão 2 Apêndice Linguagem Basic 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 Do Segunda, 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 Do Terceira, 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 Do Quarta, teste no final do comando com WHILE: DO faça executa bloco de comandos LOOP WHILE (expressão) ENQUANTO expressão for True Quinta, teste no final do comando com UNTIL: DO faça executa bloco de comandos Introdução ao OpenOffice.org Basic 141

144 Apêndice Linguagem Basic Versão 2 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() ) leia a linha processe a linha Loop faça enquanto não for Fim de Arquivo 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. 142 Introdução ao OpenOffice.org Basic

145 Versão 2 Apêndice Linguagem Basic 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 SUB A 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) Introdução ao OpenOffice.org Basic 143

146 Apêndice Linguagem Basic Versão 2 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 FUNCTION Note 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. 144 Introdução ao OpenOffice.org Basic

147 Versão 2 Apêndice Linguagem Basic 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#) END SUB cadeia = Ltrim$(Rtrim$(cadeia) +, + Str$(X) +, + Str$(Y) Print cadeia a mudança em cadeia, será descartada no término da Sub Chamada de Procedimentos A chamada a um procedimento depende do seu tipo, se sub-rotina ou função. Como uma subrotina 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ênteses CALL 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, coordy Se 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 arecirc arecirc = areacirculo (raio) chama 2 funcoes, areacirculo ( ) e Str$ ( ) o valor retornado será atribuído a cadeia cadeia = Str$( areacirculo ( raio ) ) chama 2 funcoes, Sqr ( ) e Distancia ( ) o valor retornado será atribuído a raizdist raizdist = 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$ ) Introdução ao OpenOffice.org Basic 145

148 Apêndice Linguagem Basic Versão 2 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. 146 Introdução ao OpenOffice.org Basic

149 Versão 2 Mais informações 10 Mais informações 10.1 Na rede OpenOffice.org : O lar do OpenOffice.org Projeto de Documentação do OpenOffice.org: OpenOffice.org for Developers Este é o local para quem está interessado em desenvolvimento com o OpenOffice.org. Aqui, você encontra: OpenOffice.org 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 Documentação, fóruns ( inclusive sobre Macros) e notícias do OpenOffice.org. OOOForum.Org Fóruns do OpenOffice.org, inclusive sobre Macros e API. OOExtras 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 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 Contém o DevGuide, com exemplos do Developers 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. Introdução ao OpenOffice.org Basic 147

150 Mais informações Versão 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/ 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 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. 148 Introdução ao OpenOffice.org Basic

151 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 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. Introdução ao OpenOffice.org Basic 149