Sumário

# A Biblioteca ScriptForge

Para acessar este comando...

Vá em Ferramentas - Macros - LibreOffice Basic - Editar e selecione o container Macros e caixas de diálogo do LibreOffice.

As bibliotecas ScriptForge criam uma coleção extensível de recursos de script de macro para oLibreOffice para serem chamados de macros Basic ou scripts Python.

• Macros BASIC precisam carregar a biblioteca ScriptForge usando a seguinte instrução:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
• Scripts Python exigem uma importação do módulo scriptforge:
from scriptforge import CreateScriptService

Para saber mais sobre como criar e executar scripts em Python usando a biblioteca ScriptForge leia a página Criando Scripts Python com o ScriptForge.

## Invocando serviços ScriptForge

Os módulos e classes descritos são invocados a partir de scripts de usuários como "Serviços". Um construtor genérico desses serviços foi desenvolvido para cada linguagem.

O método Dispose está disponível em todos os serviços e deve ser chamado para liberar recursos após o uso:

##### Em Basic

        GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
        Set oSvc = CreateScriptService("servicename"[, arg0, arg1, ...])
        ' ...
        oSvc.Dispose()

##### Em Python

        from scriptforge import CreateScriptService
        svc = CreateScriptService('servicename'[, arg0, arg1, ...])
        # ...
        svc.Dispose()

## Serviços disponibilizados pela biblioteca ScriptForge

Categoria | Serviços
--- | ---
LibreOffice Basic | Array Dictionary | Exception FileSystem | String TextStream
Conteúdo do documento | Base Calc Chart | Database Dataset Datasheet | Document FormDocument Writer
Interface de usuário | Dialog DialogControl Form | FormControl Menu PopupMenu | Toolbar ToolbarButton UI
Utilitários | Basic L10N Platform | Region Services Session | Timer UnitTest

## Serviço ScriptForge.Array

Fornece uma coleção de métodos para manipular e transformar Arrays de uma dimensão (vetores) e Arrays de duas dimensões (matrizes). Isso inclui operações de conjuntos, ordenação, bem como importação e exportação de arquivos texto.

Arrays com mais de duas dimensões não podem ser usados em métodos deste serviço, com a única exceção do método CountDims que aceita arrays com qualquer número de dimensões.

## Serviço SFDocuments.Base

O serviço Base oferece vários métodos e propriedades para facilitar o gerenciamento e o manuseio de documentos do LibreOffice Base.

Este serviço está intimamente relacionado ao serviço Document, que fornece métodos genéricos para lidar com documentos do LibreOffice, incluindo documentos Base. Portanto, o serviço Base estende o serviço Document e fornece métodos adicionais que são específicos para documentos Base, permitindo aos usuários:

- Obter acesso ao banco de dados contido num documento Base.

- Abrir documentos de formulário armazenados num documento Base.

- Verificar se um documento de formulário de um documento Base está carregado no momento.

## Serviço ScriptForge.Basic

O serviço ScriptForge.Basic propõe uma coleção de métodos LibreOffice Basic a serem executados em um contexto Python. Os métodos de serviço Basic reproduzem a sintaxe e o comportamento exatos das funções integradas do Basic.

## Serviço SFDocuments.Calc

A biblioteca compartilhada SFDocuments fornece diversos métodos e propriedades que facilitam a gestão e manuseio de documentos do LibreOffice.

O serviço SFDocuments.Calc é uma subclasse do serviço SFDocuments.Document. Todos os métodos e propriedades definidas para o serviço Document podem também serem acessados utilizando uma instância do serviço Calc.

O serviço Calc tem como foco:

- Manusear planilhas em um documento Calc (copiar, inserir, mover, etc)

- Trocar dados entre estruturas de dados Basic e células no Calc

- Copiar e importar grandes quantidades de dados

## Serviço SFDocuments.Chart

O serviço Chart fornece um conjunto de propriedades e métodos para manipular gráficos em documentos Calc. Com este serviço é possível:

- Acessar objetos de gráficos em documentos Calc e manipular suas propriedades.

- Criar e inserir novos gráficos em um documento Calc.

- Exportar gráficos como arquivos de imagem.

## Serviço SFDatabases.Database

O serviço Database permite o acesso a bancos de dados embutidos ou descritos por documentos Base. Este serviço fornece métodos para:

- Obter acesso aos dados de tabelas em bancos de dados

- Realizar consultas SELECT e executar funções agregadas.

- Realizar ações baseadas em comandos SQL como INSERT, UPDATE, DELETE, etc.

## Serviço SFDatabases.Dataset

O serviço Dataset é usado para representar dados tabulares produzidos por um banco de dados. Com este serviço é possível:

- Navegar e acessar os dados em um conjunto de dados.

- Atualizar, inserir e remover registros em um conjunto de dados.

## Serviço SFDatabases.Datasheet service

O serviço Datasheet permite visualizar o conteúdo das tabelas do banco de dados, bem como os resultados das consultas e instruções SQL usando o Data View do Base. Adicionalmente, este serviço permite:

- Adicionar menus personalizados à exibição de dados.

- Acessar valores em posições específicas da exibição de dados.

- Posicionar o cursor em uma célula específica da exibição de dados.

## Serviço SFDialogs.Dialog

O serviço Dialog contribui para o gerenciamento de diálogos criados com o Editor de Diálogos Basic ou diálogos criados dinamicamente. Cada instância da classe atual representa uma única caixa de diálogo exibida ao usuário.

## Serviço SFDialogs.DialogControl

O serviço DialogControl gerencia os controles pertencentes a caixas de diálogo criadas com o Editor de Diálogos do Basic. Cada instância deste serviço representa um único controle em uma caixa de diálogo.

O foco deste serviço está na obtenção e definição de valores apresentados pelos controles de uma caixa de diálogo. A formatação é acessível por meio das propriedades XControlModel e XControlView.

Note que o conteúdo da propriedade DialogControl.Value varia de acordo com o tipo do controle.

Atenção especial é dada aos controles do tipo Árvore. É fácil povoar uma árvore, tanto ramo a ramo como diversos ramos de uma única vez. Inserir itens em um controle do tipo Árvore pode ser feito tanto de maneira estática como dinâmica.

## Serviço ScriptForge.Dictionary

Um dicionário é uma coleção de pares de chaves-itens.

- Uma chave é uma string não sensível ao caso.

- Itens podem ser de qualquer tipo.

## Serviço SFDocuments.Document

A biblioteca SFDocuments fornece métodos e propriedades que facilitam a gestão e manuseio de documentos do LibreOffice.

Métodos aplicáveis a todos os tipos de documentos (documentos de texto, planilhas, apresentações, etc.) são disponibilizados pelo serviço SFDocuments.Document. Alguns exemplos são:

- Abrir, fechar e salvar documentos

- Acessar propriedades padrão e customizadas dos documentos

## Serviço ScriptForge.Exception

O serviço Exception fornece uma coleção de métodos que ajudam a depurar scripts em Basic e Python e também auxiliam na manipulação de exceções em scripts escritos em Basic.

Em scripts Basic, quando um erro de em tempo de execução ocorre, os métodos e propriedades do serviço Exception ajudam a identificar o contexto do erro e ajudam na sua manipulação.

## Serviço ScriptForge.FileSystem

O serviço FileSystem inclui rotinas para manusear arquivos e pastas. A seguir estão alguns exemplos do que pode ser feito com este serviço:

- Verificar se um arquivo existe ou não.

- Criar e apagar pastas e arquivos.

- Abrir caixas de diálogo para abrir/salvar arquivos.

- Acessar a lista de arquivos e pastas, etc.

## Serviço SFDocuments.Form

O serviço Form fornece métodos e propriedades para gerenciar formulários em documentos do LibreOffice. Este serviço suporta formulários de documentos Base, Calc e Writer e permite:

- Abrir e ativar formulários.

- Navegar pelos registros mostrados no formulário.

- Acessar os controles do formulário.

- Acessar os subformulários de um formulário pai.

## Serviço SFDocuments.FormControl

O serviço FormControl provê acesso aos controles que pertencem a um formulário, subformulário ou controle de tabela de um FormDocument. Cada instância do serviço FormControl se refere a um único controle no formulário. Este serviço permite:

- Obter e definir as propriedades do controle representado pela instância FormControl.

- Acessa o valor atual mostrado pelo controle.

- Coloca o foco no controle desejado.

## Serviço SFDocuments.FormDocument

O serviço FormDocument permite acessar documentos de formulário armazenados em documentos do LibreOffice Base.

Em um documento Base, os documentos de formulário existentes podem ser visualizados selecionando Exibir - Formulários na interface do usuário. Cada documento de formulário pode ser composto por um ou mais formulários, incluindo o formulário principal e outros subformulários.

## Serviço ScriptForge.L10N

Este serviço fornece diversos métodos relacionados à tradução de Strings com impacto mínimo no código fonte do programa. Os métodos disponibilizados pelo serviço L10N podem ser usados para:

- Criar arquivos POT que podem ser usados como modelos para tradução de todas as strings de um programa.

- Buscar Strings traduzidas durante a execução para o idioma definido na propriedade Locale.

## Serviço SFWidgets.Menu

O serviço Menu pode ser usado para criar e remover menus da barra de menus de uma janela de documento do LibreOffice. Cada entrada do menu pode ser associada a uma macro ou comando UNO. Este serviço fornece as seguintes possibilidades:

- Criação de menus com entradas customizadas, que podem ser comandos simples, caixas de verificação, botões de opção e separadores.

- Decoração de itens do menu com ícones e textos com dicas.

## Serviço ScriptForge.Platform

O serviço Platform fornece um conjunto de propriedades sobre o ambiente de execução atual e seu contexto, incluindo:

- A plataforma de hardware (arquitetura, contagem de núcleos do CPU, tipo de máquina, etc)

- Informações sobre o sistema operacional (Tipo do sistema, lançamento, versão, etc)

- A versão do LibreOffice

- Nome de usuário atual

## Serviço SFWidgets.PopupMenu

O serviço PopupMenu pode ser usado para criar menus de popup que podem ser associados a eventos ou executados por scripts. O serviço fornece as seguintes funcionalidades:

- Criação de menus de popup com entradas customizadas, caixas de seleção e botões de opção.

- Decoração de itens do menu com ícones e textos com dicas.

## Serviço ScriptForge.Region

O serviço Region fornece um conjunto de propriedades e métodos para manipular aspectos de programação relacionados à localidade e região, tais como:

- Acessar configurações dependentes da localidade e região como o formato de números, moeda e fuso horário.

- Converter fusos horários e calcular deslocamentos de horário de verão.

- Transformar números em texto em qualquer um dos idiomas suportados.

## Serviço ScriptForge.Services

O principal objetivo do módulo Services é prover acesso ao método CreateScriptService, o qual pode ser chamado em scripts de usuário para instanciar serviços que são implementados usando o framework ScriptForge.

## Serviço ScriptForge.Session

O serviço Session reúne diversos métodos de propósito geral sobre:

- A instalação ou ambiente de execução

- Introspecção UNO

- A invocação de scripts externos ou programas

## Serviço ScriptForge.String

O serviço String fornece um conjunto de métodos para processamento de Strings. Tais métodos podem ser usados para:

- Validar os conteúdos das Strings.

- Formatar, aparar, justificar e inserir quebras automáticas em Strings

- Usar expressões regulares para buscar e substituir sub-strings.

- Aplicar algoritmos de hash em strings, etc.

## Serviço ScriptForge.TextStream

O serviço TextStream é usado para ler e escrever sequencialmente de/para arquivos abertos usando o serviço ScriptForge.FileSystem service.

Os métodos OpenTextFile e CreateTextFile do serviço FileSystem retornam uma instância do serviço TextStream.

## Serviço ScriptForge.Timer

O serviço Timer mede o tempo para executar scripts de usuário.

Um Timer mede durações. Ele pode ser:

- Iniciado, para indicar quando a medição do tempo teve início.

- Suspenso, para pausar a medição do tempo de execução.

- Retomado, para continuar a medição do tempo de execução após a suspensão do Timer.

- Reiniciado, o que cancelará medições anteriores e inicializará o Timer em zero.

## Serviço SFWidgets.Toolbar

O serviço Toolbar permite recuperar informações relacionadas às barras de ferramentas disponíveis em uma janela específica do documento. Com este serviço é possível:

- Alternar a visibilidade de barras de ferramentas específicas.

- Acessar informações sobre os botões disponíveis em cada barra de ferramentas.

## Serviço SFWidgets.ToolbarButton

O serviço ToolbarButton permite recuperar informações relacionadas aos botões da barra de ferramentas disponíveis em uma determinada barra de ferramentas. Com este serviço é possível:

- Alternar a visibilidade dos elementos da barra de ferramentas.

- Executar o comando associado a um determinado botão da barra de ferramentas.

## Serviço ScriptForge.UI

O serviço UI (do inglês, User Interface - Interface de Usuário) simplifica a identificação e manipulação das diferentes janelas que compõem toda a aplicação do LibreOffice:

- Seleção de janelas

- Redimensionamento e movimentação de janelas

- Ajustes da barra de status

- Apresentação de uma barra de progresso flutuante

- Criação de novas janelas

- Acesso aos documentos

## Serviço SFUnitTests.UnitTest

O serviço UnitTest fornece um framework para automatização de testes de unidade usando a linguagem Basic, incluindo a possibilidade de:

- Agregar casos de teste em suítes de teste e testes de unidade.

- Compartilhar código de preparação e finalização entre testes de caso.

- Reportar os resultados dos testes usando o Console.

## Serviço SFDocuments.Writer

A biblioteca compartilhada SFDocuments fornece diversos métodos e propriedades que facilitam a gestão e manuseio de documentos do LibreOffice.

Alguns métodos são genéricos para todos os tipos de documentos e são herdados do módulo SF_Document, enquanto outros métodos que são específicos para documentos do Writer são definidos no módulo SF_Writer.

Nota: Outros módulos do ScriptForge não descritos aqui são reservados para uso interno. Seu conteúdo está sujeito a mudanças sem aviso prévio.

Todas as rotinas ou identificadores do ScriptForge em Basic que possuem o caractere "_" como prefixo são reservadas para uso interno. Elas não devem ser usadas em macros escritas em Basic ou em Python.