Conteúdo
Índice 🔎︎

# Serviço ScriptForge.Services

A biblioteca ScriptForge é construída com uma coleção extensível de Serviços.
Esta coleção é implementada como categorias de bibliotecas Basic ou módulos Python.

1. a biblioteca ScriptForge padrão fornecida com o LibreOffice

2. uma variedade de bibliotecas "associadas" que também são fornecidas com o LibreOffice

3. qualquer extensão do LibreOffice feita por usuários/contribuidores que desejam se encaixar no mesmo framework.

Um serviço é uma coleção de propriedades ou métodos que implementam o serviço.

Para o autor de um script de usuário, um serviço pode ser um module dentro de uma biblioteca ou uma instância de um módulo de classe.

Um gerenciador de eventos é um script contido em uma biblioteca que conecta um evento que dispara uma macro - definida pelo usuário no menu Ferramentas - Personalizar - à respectiva instância do serviço.

Como um exemplo, se diversos documentos disparam a mesma macro quando são carregados, pode ser útil saber qual documento disparou a macro em um determinado momento. São em situações como essa que o gerenciador de eventos faz seu papel.

Os seguintes métodos compõem o núcleo do framework ScriptForge:

- RegisterScriptServices

  Chamado internamento pelo ScriptForge para registrar a lista de serviços implementados por uma biblioteca.
  Cada biblioteca associada ao Scriptforge ou que a estende deve implementar seu próprio método RegisterScriptServices.

- RegisterService

  Chamado para cada serviço a ser registrado na biblioteca pelo método RegisterScriptServices.

- RegisterEventManager

  Chamado para registrar um gerenciador de eventos de biblioteca pelo método RegisterScriptServices.

- CreateScriptService

  Chamado por scripts de usuário para obter um objeto dando acesso ao serviço passado como argumento.
  Todos os serviços devem ser invocados através do método CreateScriptService.

Por convenção, os serviços String, Array e Exception podem ser invocados diretamente usando SF_String, SF_Array e SF_Exception, respectivamente.

Lista de Métodos no Serviço Service
CreateScriptService | RegisterScriptServices RegisterService | RegisterEventManager

## CreateScriptService

Obtém acesso a um dos serviços de uma biblioteca para ser usado em um script de usuário.
O valor retornado é um objeto Basic ou Nothing se um erro ocorrer.

Um serviço pode ser entendido como:

- Um conjunto de métodos reunidos em um módulo Basic padrão.

- Um conjunto de métodos e propriedades reunidos em um módulo de classe Basic.

### Sintaxe:

           CreateScriptService(Service As String, [arg0, ...] As Variant) As Variant

### Parâmetros:

Service: Nome do serviço identificado como "biblioteca.serviço".
A "biblioteca" é uma biblioteca Basic que deve existir em GlobalScope. O valor padrão é "ScriptForge".
O "serviço" é um dos serviços registrados pela biblioteca por meio do método RegisterScriptServices().

arg0, ...: Lista de argumentos requeridos para invocar o serviço.
Se o primeiro argumento se referir a um gerenciador de eventos, então arg0 é obrigatório e deve ser o objeto UNO representando o evento passado como argumento para a macro de usuário.

### Exemplo:

            GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
            ' A ser feito apenas uma vez
            Dim svc As Object
            Set svc = CreateScriptService("Array")
            ' Refere-se ao serviço "ScriptForge.Array" ou SF_Array
            Set svc = CreateScriptService("ScriptForge.Dictionary")
            ' Retorna uma instância com um novo dicionário vazio; "ScriptForge" é opcional
            Set svc = CreateScriptService("SFDocuments.Calc")
            ' Refere-se ao serviço Calc, implementado na biblioteca associada SFDocuments
            Set svc = CreateScriptService("Timer", True)
            ' Retorna uma instância do serviço Timer e é iniciado imediatamente
            Set svc = CreateScriptService("SFDocuments.DocumentEvent", oEvent)
            ' Refere-se ao serviço DocumentEvent implementado na biblioteca associada SFDocuments
            ' Retorna a instância do serviço Document que disparou o evento

## RegisterScriptServices

Ao executar uma sequência de invocações dos métodos RegisterService() e RegisterEventManager(), o método RegisterScriptServices() incorpora uma biblioteca ao framework ScriptForge.
Cada biblioteca pertencente ao framework deve implementar sua própria versão deste método.

O método deve ser armazenado em um módulo Basic padrão em vez de um módulo de classe.

Um serviço é:

- Um módulo Basic padrão passado como um objeto Basic.

- Uma String designando a função a ser executada para obter uma instância do serviço. Trata-se da função contendo a palavra-chave New de uma instrução Set que cria a instância.

              GlobalScope.LibraryName.ModuleName ' Objeto
              "LibraryName.ModuleName.FunctionName" ' String

### Exemplo:

          Public Sub RegisterScriptServices()
          ' To be stored in library = myLibrary
              With GlobalScope.ScriptForge.SF_Services
                  .RegisterService("myService1", GlobalScope.myLibrary.myModule)
                  ' Refere-se a um módulo padrão Basic que implementa o serviço como um conjunto de métodos
                  .RegisterService("myService2", "myLibrary.someModule.someFunction")
                  ' A função deve retornar uma instância de um objeto de classe Basic implementando o serviço
                  ' ...
              End With
          End Sub

Quando um script de usuário contém uma instrução como:

    Set myServ = CreateScriptService("myLibrary.myService1")

ScriptForge executa estas tarefas:

1. Carrega a biblioteca myLibrary quando necessário

2. Invoca o método RegisterScriptServices para carregar a lista de serviços de myLibrary na memória

3. Inicializa a variável myServ com o serviço dado

## RegisterService

O método retorna True se o par nome-valor especificado como argumento pode ser registrado com sucesso.

### Sintaxe:

          GlobalScope.ScriptForge.SF_Services.RegisterService(ServiceName As String, ServiceReference As Variant) As Boolean

### Parâmetros:

ServiceName: Nome do serviço como uma String sensível à caixa. O nome deve ser único.

ServiceReference: Uma referência de serviço pode ser:

- Um módulo Basic padrão passado como um objeto Basic.

- Uma String designando a função a ser executada para obter uma instância do serviço. Trata-se da função contendo a palavra-chave New de uma instrução Set que cria a instância.

              GlobalScope.LibraryName.ModuleName ' Objeto
              "LibraryName.ModuleName.FunctionName" ' String

### Exemplo:

              With GlobalScope.ScriptForge.SF_Services
                  .RegisterService("myService1", GlobalScope.myLibrary.myModule)
                  ' Refere-se a um módulo padrão Basic que implementa o serviço como um conjunto de métodos
                  .RegisterService("myService2", "myLibrary.someModule.someFunction")
                  ' A função deve retornar uma instância de um objeto de classe Basic implementando o serviço
                  ' ...
              End With

## RegisterEventManager

O método retorna True se o par nome-valor especificado como argumento pode ser registrado com sucesso.

### Sintaxe:

          GlobalScope.ScriptForge.SF_Services.RegisterEventManager(ServiceName As String, ServiceReference As String) As Boolean

### Parâmetros:

ServiceName: Nome do serviço como uma String sensível à caixa. O nome deve ser único.

ServiceReference: Uma String designando a função a ser executada para obter uma instância do serviço. Trata-se da função contendo a palavra-chave New de uma instrução Set que cria a instância.

        "LibraryName.ModuleName.FunctionName" ' String

### Exemplo:

              With GlobalScope.ScriptForge.SF_Services
                  .RegisterEventManager("myEventMgr", "myLibrary.someModule.someFunction")
                  ' A função deve retornar uma instância de um objeto de classe Basic implementando o serviço
                  ' ...
              End With

Todas as rotinas básicas ou identificadores do ScriptForge que possuem o caractere "_" como prefixo são reservados apenas para uso interno. Elas não devem ser usadas em macros Basic.

Tópicos relacionados

Instrução Set

Especificador GlobalScope