Conteúdo

# A biblioteca ScriptForge

Para aceder a este comando...

Abra Ferramentas - Macros - LibreOffice Básicas - Editar e selecione o contentor Macros da aplicação.

As bibliotecas ScriptForge constituem uma coleção extensível de recursos de scripts de macros para o LibreOffice, que podem ser invocados a partir de macros Basic ou scripts Python.

• As macros básicas requerem o carregamento da biblioteca ScriptForge através da seguinte instrução:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
• Os scripts Python requerem a importação do módulo scriptforge:
from scriptforge import CreateScriptService

Para saber mais sobre como criar e executar scripts Python utilizando a biblioteca ScriptForge, consulte a página de ajuda Criação de scripts Python com o ScriptForge.

## Invocar serviços ScriptForge

Os módulos e classes descritos são chamados a partir de scripts do utilizador como «Serviços». Para esse efeito, foi concebido um construtor genérico desses serviços para cada linguagem.

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

##### 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 Básico | Array Dictionary | Exception FileSystem | String TextStream
Conteúdo do documento | Base Calc Chart | Database Dataset Datasheet | Document FormDocument Writer
Interface do utilizador | ContextMenu Dialog DialogControl Form | FormControl Menu PopupMenu | Toolbar ToolbarButton UI
Utilitários | Basic L10N Platform | Region Services Session | Timer UnitTest

## ScriptForge.Array serviço

Fornece um conjunto de métodos para manipular e transformar matrizes unidimensionais (vetores) e bidimensionais (matrizes). Isto inclui operações com conjuntos, ordenação, importação e exportação para ficheiros de texto.

As matrizes com mais de duas dimensões não podem ser utilizadas com os métodos deste serviço, sendo a única exceção o método CountDims, que aceita matrizes com qualquer número de dimensões.

## Serviço.SFDocumentsBase

O serviço Base disponibiliza vários métodos e propriedades para facilitar a gestão e o manuseamento de documentos LibreOffice Base.

Este serviço está intimamente relacionado com o serviço Document, que fornece métodos genéricos para o tratamento de documentos LibreOffice, incluindo documentos Base. Por conseguinte, o serviço Base estende o serviço Document e fornece métodos adicionais específicos para documentos Base, permitindo aos utilizadores:

- Obter acesso à base de dados contida num documento Base.

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

- Verifique se está carregado um documento de formulário proveniente de um documento Base.

## Serviço.ScriptForge Basic

O serviço ScriptForge.Basic disponibiliza um conjunto de métodos LibreOffice Basic para serem executados num contexto Python. Os métodos do serviço Basic reproduzem exatamente a sintaxe e o comportamento das funções integradas do Basic.

## Serviço SFDocuments.Calc

A biblioteca partilhada SFDocuments disponibiliza vários métodos e propriedades para facilitar a gestão e o manuseamento de documentos LibreOffice.

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

O serviço Calc centra-se em:

- Manipular folhas num documento do Calc (copiar, inserir, mover, etc.)

- Troca de dados entre estruturas de dados básicas e intervalos do Calc

- Copiar e importar grandes quantidades de dados

- Formatação simples de intervalos de células

## Serviço SFDocuments.Chart

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

- Aceda aos objetos do gráfico em documentos do Calc e altere as suas propriedades.

- Criar e inserir novos gráficos num documento do Calc.

- Exportar gráficos como ficheiros de imagem.

## SFWidgets.ContextMenu serviço

Os menus de contexto são predefinidos durante a instalação do LibreOffice. Podem ser personalizados na caixa de diálogo Ferramentas + Personalizar.

O serviço ContextMenu oferece as seguintes funcionalidades:

- Substituir temporariamente todos os itens de um menu de contexto específico.

- Adicione temporariamente novos itens de menu na parte inferior de um menu de contexto predefinido.

- Desativar temporariamente o menu de contexto.

## Serviço SFDatabases.Database

O serviço Database permite aceder a bases de dados incorporadas ou descritas em documentos Base. Este serviço disponibiliza métodos para:

- Aceda aos dados nas tabelas da base de dados.

- Executar consultas SELECT e aplicar funções de agregação.

- Executar instruções SQL como INSERT, UPDATE, DELETE, etc.

## SFDatabases.Dataset service

O serviço Dataset é utilizado para representar dados tabulares produzidos por uma base de dados. Com este serviço, é possível:

- Navegar e aceder aos dados de um conjunto de dados.

- Atualizar, inserir e eliminar registos num conjunto de dados.

## SFDatabases.Datasheet service

O serviço Datasheet permite visualizar o conteúdo das tabelas da base de dados, bem como os resultados de consultas e instruções SQL, utilizando a Visualização de Dados do Base. Além disso, este serviço permite:

- Coloque o cursor numa célula específica da visualização de dados.

- Aceder aos valores em posições específicas da visualização de dados.

- Coloque o cursor numa célula específica da visualização de dados.

## SFDialogs.Dialog serviço

O serviço Dialog contribui para a gestão de caixas de diálogo criadas com o Editor de Diálogos do Basic ou criadas dinamicamente. Cada instância da classe atual representa uma única caixa de diálogo apresentada ao utilizador.

## SFDialogs.DialogControl serviço

O serviço DialogControl gere os controlos pertencentes a uma caixa de diálogo definida com o Editor de Caixas de Diálogo da Basic. Cada instância do serviço atual representa um único controlo dentro de uma caixa de diálogo.

O foco está em obter e definir os valores apresentados pelos controlos da caixa de diálogo. A formatação é acedida através das propriedades XControlModel e XControlView.

Note-se que o conteúdo da propriedade DialogControl.Value, que é único, varia consoante o tipo de controlo.

Note-se que o conteúdo da propriedade DialogControl.Value, que é único, varia consoante o tipo de controlo.

## ScriptForge.Dicionário serviço

Um dicionário é uma coleção de pares chave-elemento

- A chave é uma cadeia de caracteres. Nos scripts em Basic, a distinção entre maiúsculas e minúsculas da chave é determinada aquando da criação do dicionário. Nos scripts em Python, a chave distingue sempre entre maiúsculas e minúsculas.

- Os artigos podem ser de qualquer tipo

## SFDocuments.Document serviço

A biblioteca SFDocuments disponibiliza métodos e propriedades para facilitar a gestão e a manipulação de documentos LibreOffice.

Os métodos aplicáveis a todos os tipos de documentos (documentos de texto, folhas de cálculo, apresentações, etc.) são fornecidos pelo serviço SFDocuments.Document. Alguns exemplos são:

- Abrir, fechar e guardar documentos

- Aceder a propriedades padrão ou personalizadas dos documentos

## ScriptForge.Exception serviço

O serviço Exception é um conjunto de métodos destinados a auxiliar na depuração de código em scripts Basic e Python e no tratamento de erros em scripts Basic.

Nos scripts Basic, quando ocorre um erro em tempo de execução, os métodos e propriedades do serviço Exception ajudam a identificar o contexto do erro e permitem tratá-lo.

## ScriptForge.FileSystem serviço

O serviço FileSystem inclui rotinas para gerir ficheiros e pastas. Seguem-se alguns exemplos das funcionalidades disponibilizadas por este serviço:

- Verificar se um ficheiro ou pasta existe.

- Criar e eliminar pastas e ficheiros.

- Abrir caixas de diálogo para abrir/guardar ficheiros.

- Aceder à lista de ficheiros numa pasta, etc.

## SFDocuments.Form serviço

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

- Abrir e ativar formulários.

- Navegue pelos registos apresentados no formulário.

- Obtenha acesso aos controlos dentro do formulário.

- Obter acesso aos subformulários de um formulário principal.

## SFDocuments.FormControl serviço

O serviço FormControl permite aceder aos controlos que pertencem a um formulário, a um subformulário ou a um controlo de tabela de um FormDocument. Cada instância do serviço FormControl refere-se a um único controlo no formulário. Este serviço permite aos utilizadores:

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

- Aceda ao valor atual apresentado pelo controlo.

- Selecione o controlo pretendido.

## SFDocuments.FormDocument serviço

O serviço FormDocument permite aceder a documentos de formulário armazenados nos documentos base LibreOffice.

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

## ScriptForge. Serviço L10N

Este serviço disponibiliza vários métodos relacionados com a tradução de cadeias de caracteres, com um impacto mínimo no código-fonte do programa. Os métodos disponibilizados pelo serviço L10N podem ser utilizados principalmente para:

- Crie ficheiros POT que possam ser utilizados como modelos para a tradução de todas as cadeias de texto do programa.

- Obter cadeias traduzidas em tempo de execução para o idioma definido na propriedade Locale.

## SFWidgets.Menu service

The Menu service can be used to create and remove menus from the menubar of a LibreOffice document window. Each menu entry can be associated with a script or with a UNO command. This service provides the following capabilities:

- Creation of menus with custom entries, checkboxes, radio buttons and separators.

- Decoration of menu items with icons and tooltips.

## ScriptForge.Platform service

The Platform service provides a collection of properties about the current execution environment and context, such as:

- The hardware platform (architecture, CPU count, machine type, etc)

- Operating system information (OS type, release, version, etc)

- The LibreOffice version

- The current user name

## SFWidgets.PopupMenu service

The PopupMenu service can be used to create popup menus that can be associated with events or executed by scripts. This service provides the following capabilities:

- Creation of popup menus with custom entries, checkboxes and radio buttons.

- Decoration of menu items with icons and tooltips.

## ScriptForge.Region service

The Region service provides a collection of properties and methods to handle locale and region-related aspects of programming, such as:

- Accessing locale and region-dependent settings such as number formatting, currency and timezones.

- Converting timezones and calculate Daylight Saving Time (DST) offsets.

- Transforming numbers into text in any supported language.

## ScriptForge.Services service

The main purpose of the Services module is to provide access to the CreateScriptService method, which can be called in user scripts to instantiate services that are implemented using the ScriptForge framework.

## ScriptForge.Session service

The Session service gathers various general-purpose methods about:

- the installation or execution environment

- UNO introspection

- the invocation of external scripts or programs

## ScriptForge.String service

The String service provides a collection of methods for string processing. These methods can be used to:

- Validate the contents of strings

- Format strings by trimming, justifying or wrapping their contents

- Use regular expressions to search and replace substrings

- Apply hash algorithms on strings, etc.

## ScriptForge.TextStream service

The TextStream service is used to sequentially read from and write to files opened or created using the ScriptForge.FileSystem service.

The methods OpenTextFile and CreateTextFile from the FileSystem service return an instance of the TextStream service.

## ScriptForge.Timer service

The Timer service measures the amount of time it takes to run user scripts.

A Timer measures durations. It can be:

- Started, to indicate when to start measuring time.

- Suspended, to pause measuring running time.

- Resumed, to continue tracking running time after the Timer has been suspended.

- Restarted, which will cancel previous measurements and start the Timer at zero.

## SFWidgets.Toolbar service

The Toolbar service allows to retrieve information related to the toolbars available for a specific document window. With this service it is possible to:

- Toggle the visibility of specific toolbars.

- Access information about the buttons available in each toolbar.

## SFWidgets.ToolbarButton service

The ToolbarButton service allows to retrieve information related to the toolbar buttons available in a given toolbar. With this service it is possible to:

- Toggle the visibility of toolbar elements.

- Execute the command associated with a given toolbar button.

## ScriptForge.UI service

The UI (User Interface) service simplifies the identification and the manipulation of the different windows composing the whole LibreOffice application:

- Windows selection

- Windows moving and resizing

- Statusbar settings

- Display of a floating progress bar

- Creation of new windows

- Access to the underlying "documents"

## SFUnitTests.UnitTest service

The UnitTest service provides a framework for automating unit tests using the Basic language, including the ability to:

- Aggregate test cases into test suites and unit tests.

- Share setup and shutdown code among test cases.

- Report test results using the Console.

## SFDocuments.Writer service

The SFDocuments shared library provides a number of methods and properties to facilitate the management and handling of LibreOffice documents.

Some methods are generic for all types of documents and are inherited from the SF_Document module, whereas other methods that are specific for Writer documents are defined in the SF_Writer module.

Nota: Outros módulos do ScriptForge não descritos estão reservados para uso interno. O seu conteúdo está sujeito a alterações sem aviso prévio.

Todas as rotinas ou identificadores do ScriptForge Basic que tenham o caractere de sublinhado «_» como prefixo estão reservados para uso interno. Não se destinam a ser utilizados em macros do Basic ou em scripts Python.

Necessitamos da sua ajuda!