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.

tip

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.

tip

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:

tip

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:

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.

warning

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


Um serviço é:


          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:


          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
  
warning

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.


♥ Doe para nosso projeto! ♥