Escucha de eventos de documento

Escuchar los eventos del documento puede ser útil en situaciones como las siguientes:

Además de asignar macros a eventos, es posible monitorizar los eventos emitidos por los documentos de LibreOffice. Los emisores de API (interfaz de programación de aplicaciones, por sus siglas en inglés) son responsables de llamar a las macros de los eventos. A diferencia de los agentes de escucha, que requieren que se definan todos los métodos admitidos, incluso si estos no se utilizan, los monitores de documento únicamente requieren dos métodos junto a las macros conectadas de eventos.

Monitorización de los eventos del documento

A continuación se ilustra la monitorización para los lenguajes Basic y Python mediante la programación orientada a objetos. La asignación de la secuencia de órdenes OnLoad al evento Abrir documento es suficiente para iniciar y finalizar la monitorización de eventos del documento. La pestaña Eventos del menú Herramientas ▸ Personalizar se utiliza para asignar cualquiera de las dos secuencias de órdenes.

La interceptación de eventos ayuda a establecer las condiciones previas y posteriores de las secuencias de órdenes, como la carga y descarga de bibliotecas o el seguimiento del procesamiento de las secuencias de órdenes en segundo plano. El uso del módulo Access2Base.Trace ilustra este segundo contexto.

Con Python

La monitorización de eventos inicia desde la instanciación del objeto y termina cuando Python libera el objeto. Los eventos producidos se reportan mediante la consola Access2Base

note

Los eventos OnLoad y OnUnload se pueden utilizar para establecer y restablecer respectivamente la ruta de los programas de Python. Se describen como Abrir documento y Cerrar documento.



         # -*- coding: utf-8 -*-
         from __future__ import unicode_literals
             
         import os.path, uno, unohelper
         from com.sun.star.document import DocumentEvent, \
             XDocumentEventListener as AdapterPattern
         from com.sun.star.lang import EventObject
             
         class UiDocument(unohelper.Base, AdapterPattern):
             """ Monitor de eventos del documento """
             '''
             adaptado de la secuencia de órdenes 'Python script to monitor OnSave event', que se encuentra en:
             https://forum.openoffice.org/en/forum/viewtopic.php?t=68887
             '''
             def __init__(self):
                 """ Monitor de eventos del documento """
                 ''' Reporta mediante la consola Access2Base.Trace o
                 reporta en 1.ª hoja, 1.ª columna para documentos de Calc '''
                 ctx = uno.getComponentContext()
                 smgr = ctx.getServiceManager()
                 desktop = smgr.createInstanceWithContext(
                 'com.sun.star.frame.Desktop' , ctx)
                 self.doc = desktop.CurrentComponent
                 #self.row = 0  # descomentarice solo en documentos de Calc
                 Console.setLevel("DEBUG")
                 self.listen()  # Inicia seguimiento de eventos del documento
             
             @property
             def Filename(self) -> str:
                 sys_filename = uno.fileUrlToSystemPath(self.doc.URL)
                 return os.path.basename(sys_filename)
             
             def setCell(self, calcDoc, txt: str):
                 """ Saca los eventos del documento en la 1ª columna de una hoja de cálculo Calc """
                 sheet = calcDoc.getSheets().getByIndex(0)
                 sheet.getCellByPosition(0,self.row).setString(txt)
                 self.row = self.row + 1
             
             def listen(self, *args):  # OnLoad/OnNew, lo antes posible
                 """ Iniciar la monitorización de los eventos del documento """
                 self.doc.addDocumentEventListener(self)
                 Console.log("INFO", "Se están registrando los eventos del documento", True)
             
             def sleep(self, *args):  # OnUnload hasta el final (opcional)
                 """ Detener la monitorización de los eventos del documento """
                 self.doc.removeDocumentEventListener(self)
                 Console.log("INFO", "Se han registrado los eventos del documento", True)
             
             def documentEventOccured(self, event: DocumentEvent):
                 """ Intercepta todos los eventos del documento """
                 #self.setCell(event.Source, event.EventName) # solo para documentos Calc
                 Console.log("DEBUG",
                     event.EventName+" in "+self.Filename,
                     False)
             
             def disposing(self, event: EventObject):
                 """ Liberar todas las actividades """
                 self.sleep()
                 Console.show()
             
         def OnLoad(*args):  # Evento «Abrir documento»
             listener = UiDocument()  # Inicia la escucha
             
         def OnUnload(*args): # Evento «El documento se ha cerrado»
             pass  # (opcional) realizado cuando se desecha
             
         g_exportedScripts = (OnLoad,)
             
         from com.sun.star.script.provider import XScript
         class Console():
             """
             Puesta en primer o segundo plano de la consola para registrar la ejecución del programa.
             """
             @staticmethod
             def trace(*args,**kwargs):
                 """ Imprime la lista de elementos libres en la consola """
                 scr = Console._a2bScript(script='DebugPrint', module='Compatible')
                 scr.invoke((args),(),())
             @staticmethod
             def log(level: str, text: str, msgBox=False):
                 """ Anexar el mensaje de registro a la consola, con indicación opcional al usuario """
                 scr = Console._a2bScript(script='TraceLog')
                 scr.invoke((level,text,msgBox),(),())
             @staticmethod
             def setLevel(logLevel: str):
                 """ Establecer el límite inferior de los mensajes de registro """
                 scr = Console._a2bScript(script='TraceLevel')
                 scr.invoke((logLevel,),(),())
             @staticmethod
             def show():
                 """ Mostrar el contenido o un diálogo de la consola """
                 scr = Console._a2bScript(script='TraceConsole')
                 scr.invoke((),(),())
             @staticmethod
             def _a2bScript(script: str, library='Access2Base',
                 module='Trace') -> XScript:
                 ''' Coge la secuencia de órdenes Basic basada en la aplicación '''
                 sm = uno.getComponentContext().ServiceManager
                 mspf = sm.createInstanceWithContext(
                     "com.sun.star.script.provider.MasterScriptProviderFactory",
                     uno.getComponentContext())
                 scriptPro = mspf.createScriptProvider("")
                 scriptName = "vnd.sun.star.script:"+library+"."+module+"."+script+"?language=Basic&location=application"
                 xScript = scriptPro.getScript(scriptName)
                 return xScript
      
warning

Preste atención al error ortográfico en el método documentEventOccured, que proviene de la interfaz de programación de aplicaciones (API, por sus siglas en inglés) de LibreOffice.


Icono de consejo

Los eventos Iniciar aplicación and Cerrar la aplicación pueden ser usados, respectivamente, para establecer o restablecer la ruta a las secuencias de órdenes Python del usuario o de la aplicación LibreOffice. De manera similar, las bibliotecas o los módulos Python incluidos en los documentos pueden ser cargados y liberados mediante los eventos Abrir documento y Documento cerrado. Vea Importación de módulos Python para mayores detalles.


Con LibreOffice Basic

Al usar la pestaña Eventos del menú Herramientas ▸ Personalizar, el evento Abrir documento dispara una inicialización de ConsoleLogger. La rutina _documentEventOccured, establecida por Console Logger, sirve como punto de entrada único para atrapar todos los eventos de documento.

Módulo controller.Events


        Option Explicit
        
        Global _obj As Object ' instancia de controller.ConsoleLogger
        
        Sub OnLoad(evt As com.sun.star.document.DocumentEvent) ' >> Abrir documento <<
            _obj = New ConsoleLogger : _obj.StartAdapter(evt)
        End Sub ' controller.OnLoad
        Sub _documentEventOccured(evt As com.sun.star.document.DocumentEvent)
            ''' Punto de entrada único de ConsoleLogger '''
             _obj.DocumentEventOccurs(evt)
        End Sub ' controller._documentEventOccured
      

Módulo de clase controller.ConsoleLogger

La monitorización de eventos se inicia desde el momento en que se instancia un objeto ConsoleLogger y finalmente se detiene al cerrar el documento. La rutina StartAdapter carga las bibliotecas Basic necesarias, mientras que los eventos capturados se reportan mediante el módulo Access2Base.Trace.


          Option Explicit
          Option Compatible
          Option ClassModule
              
          ' Objeto del patrón de diseño ADAPTER que se instanciará en el evento "Abrir documento".
          Private Const UI_PROMPT = True
          Private Const UI_NOPROMPT = Falso ' Poner como Verdadero para visualizar los eventos de los documentos
              
          ' MIEMBROS
          Private _evtAdapter As Object ' com.sun.star.document.XDocumentEventBroadcaster
          Private _txtMsg As String ' mensaje de texto para hacer registros en la consola
              
          ' PROPIEDADES
          Private Property Get FileName As String
              ''' nombre de archivo dependiente del sistema '''
              Const _LIBRARY = "Tools" : With GlobalScope.BasicLibraries
                  If Not .IsLibraryLoaded(_LIBRARY) Then .LoadLibrary(_LIBRARY)
              End With
              Filename = Tools.Strings.FilenameOutofPath(ThisComponent.URL)
          End Property ' controller.ConsoleLogger.Filename
              
          ' MÉTODOS
          Public Sub DocumentEventOccurs(evt As com.sun.star.document.DocumentEvent)
              ''' Monitorizar eventos de documento '''
              Access2Base.Trace.TraceLog("DEBUG", _
                  evt.EventName &" in "& Filename(evt.Source.URL), _
                  UI_NOPROMPT)
              Select Case evt.EventName
                  Case "OnUnload" : _StopAdapter(evt)
              End Select
          End Sub ' controller.ConsoleLogger.DocumentEventOccurs
              
          Public Sub StartAdapter(Optional evt As com.sun.star.document.DocumentEvent)
              ''' Iniciar registro de eventos de documento '''
              Const _LIBRARY = "Access2Base" : With GlobalScope.BasicLibraries
                  If Not .IsLibraryLoaded(_LIBRARY) Then .LoadLibrary(_LIBRARY)
              End With : Access2Base.Trace.TraceLevel("DEBUG")
              If IsMissing(evt) Then _txtMsg = "" Else _txtMsg = evt.EventName & "-"
              Access2Base.Trace.TraceLog("INFO", _txtMsg & "Se están registrando los eventos del documento", UI_PROMPT)
              _evtAdapter = CreateUnoListener( "_", "com.sun.star.document.XDocumentEventListener" )
              ThisComponent.addDocumentEventListener( _evtAdapter )
          End Sub ' controller.ConsoleLogger.StartAdapter
              
          Private Sub _StopAdapter(Optional evt As com.sun.star.document.DocumentEvent)
              ''' Terminar el registro de eventos del documento '''
              ThisComponent.removeDocumentEventListener( _evtAdapter )
              If IsMissing(evt) Then _txtMsg = "" Else _txtMsg = evt.EventName & "-"
              Access2Base.Trace.TraceLog("INFO", _txtMsg & "Se registraron los eventos del documento", UI_PROMPT)
              Access2Base.Trace.TraceConsole() ' Diálogo con los eventos capturados
          End Sub ' controller.ConsoleLogger._StopAdapter
              
          ' EVENTOS
          ' Su código para la gestión de eventos va aquí
      
warning

Preste atención al error ortográfico en el método _documentEventOccured, que proviene de la interfaz de programación de aplicaciones (API, por sus siglas en inglés) de LibreOffice.


Descubrimiento de eventos de documento

El objeto API de emisora proporciona la lista de los eventos de los que es responsable:

Con Python


         # -*- coding: utf-8 -*-
         from __future__ import unicode_literals
             
         import uno, apso_utils as ui
             
         def displayAvailableEvents():
             """ Mostrar eventos del documento """
             '''
             adaptado de DisplayAvailableEvents() por A. Pitonyak
             https://forum.openoffice.org/en/forum/viewtopic.php?&t=43689
             '''
             ctx = XSCRIPTCONTEXT.getComponentContext()
             smgr = ctx.ServiceManager
             geb = smgr.createInstanceWithContext(
                 "com.sun.star.frame.GlobalEventBroadcaster", ctx)
             events = geb.Events.getElementNames()
             ui.msgbox('; '.join(events))
             
         g_exportedScripts = (displayAvailableEvents,)
      
note

La extensión Organizador Alternativo de Secuencias de Órdenes Python o Alternative Python Script Organizer (APSO) se usa para desplegar en pantalla la información de los eventos.


Con LibreOffice Basic


         Sub DisplayAvailableEvents
             ''' Mostrar eventos del documento '''
             Dim geb As Object ' com.sun.star.frame.GlobalEventBroadcaster
             Dim events() As String
             geb = CreateUnoService("com.sun.star.frame.GlobalEventBroadcaster")
             events = geb.Events.ElementNames()
             MsgBox Join(events, "; ")
         End Sub
      

¡Necesitamos su ayuda!