ScriptForge.Services service

The ScriptForge library is built upon an extensible collection of so-called "Services".
This collection is implemented as categories of Basic libraries or Python modules:

  1. the standard ScriptForge library shipped with LibreOffice

  2. a number of "associated" libraries shipped with LibreOffice as well

  3. any user/contributor LibreOffice extension wanting to fit into the same framework

A service is a collection of properties or methods which implement the service.

tip

For the author of a user script, a service may be either a module within a library, or an instance of a class module.


An event manager is a script contained in a library which binds an event triggering a macro - usually defined by the Tools - Customize menu - to the concerned service instance.

tip

As an example, if several documents trigger the same macro when they are loaded, it might be useful to know which document triggered the macro this time. That's where an event manager plays its role.


The following methods make up the kernel of the ScriptForge framework:

tip

Conventionally, the String, Array and Exception services may be invoked directly respectively as SF_String, SF_Array and SF_Exception.


Lista de métodos en el servicio Services

CreateScriptService

RegisterScriptServices
RegisterService

RegisterEventManager


CreateScriptService

Gain access to one of the services of a library for the benefit of a user script.
The returned value is a Basic object or Nothing if an error occurred.

A service can be understood as either:

Sintaxis:


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

Parámetros:

Service: The name of the service identified as "library.service".
The library is a Basic library that must exist in the GlobalScope. The default value is "ScriptForge".
The service is one of the services registered by the library via the RegisterScriptServices() method.

arg0, ...: A list of arguments required by the invoked service.
If the first argument refers to an event manager, then arg0 is mandatory and must be the UNO object representing the event provided as argument to the user macro.

Ejemplo:


        GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
        ' To be done once
        Dim svc As Object
        Set svc = CreateScriptService("Array")
        ' Refers to the "ScriptForge.Array" service or SF_Array
        Set svc = CreateScriptService("ScriptForge.Dictionary")
        ' Returns a new empty dictionary class instance; "ScriptForge." is optional
        Set svc = CreateScriptService("SFDocuments.Calc")
        ' Refers to the Calc service, implemented in the associated SFDocuments library
        Set svc = CreateScriptService("Timer", True)
        ' Returns a Timer class instance starting immediately
        Set svc = CreateScriptService("SFDocuments.DocumentEvent", oEvent)
        ' Refers to the DocumentEvent service implemented in the associated SFDocuments library
        ' Returns the instance of the Document class that fired the event
     

RegisterScriptServices

By executing a series of invocations of RegisterService() and RegisterEventManager(), the RegisterScriptServices() method incorporates a library into the ScriptForge framework.
Each library pertaining to the framework must implement its own version of this method.

warning

The method has to be stored in a standard Basic module as opposed to a class module.


Un servicio puede ser:


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

Ejemplo:


      Public Sub RegisterScriptServices()
      ' To be stored in library = myLibrary
          With GlobalScope.ScriptForge.SF_Services
              .RegisterService("myService1", GlobalScope.myLibrary.myModule)
              ' Refer to a Basic standard module implementing the service as a set of methods
              .RegisterService("myService2", "myLibrary.someModule.someFunction")
              ' La función debe devolver un ejemplar de una clase de objetos de Basic que implemente el servicio
              ' ...
          End With
      End Sub
   

When a user script contains a statement such as:

Set myServ = CreateScriptService("myLibrary.myService1")


ScriptForge performs these tasks:

  1. load the library myLibrary when necessary

  2. invoke the RegisterScriptServices method to load the list of services of myLibrary in memory

  3. initialize the variable myServ with the given service

RegisterService

The method returns True if the name-value pair given as argument could be registered successfully.

Sintaxis:


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

Parámetros:

ServiceName: The name of the service as a case-insensitive string. The name must be unique.

ServiceReference: A service reference is either:


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

Ejemplo:


          With GlobalScope.ScriptForge.SF_Services
              .RegisterService("myService1", GlobalScope.myLibrary.myModule)
              ' Refer to a Basic standard module implementing the service as a set of methods
              .RegisterService("myService2", "myLibrary.someModule.someFunction")
              ' La función debe devolver un ejemplar de una clase de objetos de Basic que implemente el servicio
              ' ...
          End With
   

RegisterEventManager

The method returns True if the name-value pair given as argument could be registered successfully.

Sintaxis:


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

Parámetros:

ServiceName: The name of the service as a case-insensitive string. The name must be unique.

ServiceReference: A string designating the function to execute to get an instance of the service. It is in fact the function containing the New keyword of a Set statement creating the instance.:

    "LibraryName.ModuleName.FunctionName" ' String

Ejemplo:


          With GlobalScope.ScriptForge.SF_Services
              .RegisterEventManager("myEventMgr", "myLibrary.someModule.someFunction")
              ' La función debe devolver un ejemplar de una clase de objetos de Basic que implemente el servicio
              ' ...
          End With
  
warning

Todas las rutinas o los identificadores Basic de ScriptForge que comienzan por un guion bajo «_» son únicamente para uso interno. No deben utilizarse en macros Basic.


¡Necesitamos su ayuda!