Contenuto
Indice 🔎︎

# Servizio ScriptForge.Services

La libreria ScriptForge è costruita basandosi su una raccolta estensibile di cosiddetti "Servizi".
Questa raccolta viene implementata con categorie di librerie in Basic o di moduli in Python:

1. la libreria ScriptForge standard fornita con LibreOffice

2. una serie di librerie "associate", fornite anch'esse con LibreOffice

3. qualsiasi estensione di LibreOffice di utenti o collaboratori che desiderano inglobarla nella stessa infrastruttura

Un service è una raccolta di proprietà e metodi che implementa il servizio.

Per l'autore di uno script utente, un servizio può essere o un modulo all'interno di una libreria, o una istanza del modulo di una classe.

Un gestore degli eventi (event manager) è uno script contenuto in una libreria che lega un evento che attiva una macro - di solito definito nel menu Strumenti - Personalizza - all'istanza del servizio interessata.

Ad esempio, se più documenti durante il loro caricamento attivano la stessa macro, potrebbe essere utile sapere quale documento ha attivato tale macro. Qui è dove il gestore degli eventi entra in gioco.

I metodi seguenti costituiscono il nocciolo del framework ScriptForge:

- RegisterScriptServices

  Viene chiamato internamente da ScriptForge per registrare l'elenco dei servizi implementati da una libreria.
  Ogni libreria associata a Scriptforge, o che la estende, deve implementare il proprio metodo RegisterScriptServices.

- RegisterService

  Viene richiamato, tante volte quanti sono i servizi da registrare nella libreria, da RegisterScriptServices.

- RegisterEventManager

  Viene chiamato da RegisterScriptServices per registrare un gestore degli eventi della libreria.

- CreateScriptService

  Viene chiamato dagli script dell'utente per ottenere un oggetto che fornisce l'accesso al servizio specificato come argomento.
  Tutti i servizi devono essere invocati attraverso il metodo CreateScriptService.

Per convenzione i servizi String, Array e Exception possono essere invocati direttamente come SF_String, SF_Array e SF_Exception, rispettivamente.

Elenco dei metodi del servizio Services
CreateScriptService | RegisterScriptServices RegisterService | RegisterEventManager

## CreateScriptService

Ottiene l'accesso a uno dei servizi della libreria a vantaggio di uno script utente.
Il valore restituito è un oggetto Basic o Nothing se si verifica un errore.

Un servizio può essere inteso come uno fra:

- un insieme di metodi raggruppati in un modulo standard di Basic

- o un insieme di metodi e proprietà raggruppati in un modulo di classi in Basic.

### Sintassi:

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

### Parametri:

Service: il nome del servizio identificato come "library.service".
La libreria è una libreria di Basic che deve esistere nel GlobalScope. Il valore predefinito è "ScriptForge".
Il servizio è uno di quelli registrati dalla libreria tramite il metodo RegisterScriptServices().

arg0, ...: un elenco di argomenti richiesti dal servizio invocato.
Se il primo argomento si riferisce a un gestore degli eventi, allora arg0 è obbligatorio e deve essere un oggetto UNO che rappresenta l'evento fornito come argomento alla macro dell'utente.

### Esempio:

            GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
            'Da eseguire una volta
            Dim svc As Object
            Set svc = CreateScriptService("Array")
            'Fa riferimento al servizio "ScriptForge.Array" o SF_Array
            Set svc = CreateScriptService("ScriptForge.Dictionary")
            'Restituisce una nuova istanza alla classe di un nuovo dizionario vuoto; "ScriptForge." è opzionale
            Set svc = CreateScriptService("SFDocuments.Calc")
            'Fa riferimento al servizio Calc, implementato nella libreria associata SFDocuments
            Set svc = CreateScriptService("Timer", True)
            'Restituisce un'istanza della classe Timer che si avvia immediatamente
            Set svc = CreateScriptService("SFDocuments.DocumentEvent", oEvent)
            'Fa riferimento al servizio DocumentEvent implementato nella libreria associata SFDocuments
            'Restituisce un'istanza della classe Document che ha innescato l'evento

## RegisterScriptServices

Eseguendo una serie di invocazioni di RegisterService() e RegisterEventManager(), il metodo RegisterScriptServices() incorpora una libreria nel framework ScriptForge.
Ogni libreria appartenente al framework deve implementare la propria versione di questo metodo.

Il metodo deve essere memorizzato in un modulo standard di Basic al contrario di un modulo di classe.

Un servizio può essere:

- un modulo standard di Basic passato come oggetto di Basic;

- o una stringa che indica la funzione da eseguire per ottenere un'istanza del servizio. Di fatto è la funzione che contiene la parola chiave New di un'istruzione Set a creare l'istanza.

              GlobalScope.LibraryName.ModuleName ' Oggetto
              "LibraryName.ModuleName.FunctionName" ' Stringa

### Esempio:

          Public Sub RegisterScriptServices()
          ' To be stored in library = myLibrary
              With GlobalScope.ScriptForge.SF_Services
                  .RegisterService("myService1", GlobalScope.myLibrary.myModule)
                  'Fa riferimento a un modulo standard di Basic che implementa il servizio come insieme di metodi
                  .RegisterService("myService2", "myLibrary.someModule.someFunction")
                  'La funzione deve restituire un'istanza di una classe di oggetti di Basic che implementa il servizio
                  ' ...
              End With
          End Sub

Quando lo script dell'utente contiene un'istruzione come:

    Set myServ = CreateScriptService("myLibrary.myService1")

ScriptForge esegue queste operazioni:

1. carica la libreria myLibrary, se necessario

2. invoca il metodo RegisterScriptServices per caricare in memoria l'elenco dei servizi di myLibrary

3. inizializza la variabile myServ con il servizio indicato

## RegisterService

Il metodo restituisce True se la coppia nome-valore indicata come argomento può essere registrata correttamente.

### Sintassi:

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

### Parametri:

ServiceName: il nome del servizio in formato stringa che non distingue tra minuscole e maiuscole. Il nome deve essere univoco.

ServiceReference - il riferimento a un servizio può essere:

- un modulo standard di Basic passato come oggetto di Basic;

- o una stringa che indica la funzione da eseguire per ottenere un'istanza del servizio. Di fatto è la funzione che contiene la parola chiave New di un'istruzione Set a creare l'istanza.

              GlobalScope.LibraryName.ModuleName ' Oggetto
              "LibraryName.ModuleName.FunctionName" ' Stringa

### Esempio:

              With GlobalScope.ScriptForge.SF_Services
                  .RegisterService("myService1", GlobalScope.myLibrary.myModule)
                  'Fa riferimento a un modulo standard di Basic che implementa il servizio come insieme di metodi
                  .RegisterService("myService2", "myLibrary.someModule.someFunction")
                  'La funzione deve restituire un'istanza di una classe di oggetti di Basic che implementa il servizio
                  ' ...
              End With

## RegisterEventManager

Il metodo restituisce True se la coppia nome-valore indicata come argomento può essere registrata correttamente.

### Sintassi:

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

### Parametri:

ServiceName: il nome del servizio in formato stringa che non distingue tra minuscole e maiuscole. Il nome deve essere univoco.

ServiceReference: una stringa che designa la funzione da eseguire per ottenere un'istanza del servizio. Di fatto è la funzione che contiene la parola chiave New di un'istruzione Set a creare l'istanza:

        "LibraryName.ModuleName.FunctionName" ' String

### Esempio:

              With GlobalScope.ScriptForge.SF_Services
                  .RegisterEventManager("myEventMgr", "myLibrary.someModule.someFunction")
                  'La funzione deve restituire un'istanza di una classe di oggetti di Basic che implementa il servizio
                  ' ...
              End With

Tutte le routine e gli identificatori Basic di ScriptForge che iniziano con un carattere di sottolineatura "_" sono riservati per uso interno. Non è previsto il loro utilizzo nelle macro in Basic.

Argomenti correlati

Istruzione Set

Modificatore GlobalScope