Contenido

# Escucha de eventos de documento

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

- Identificar un nuevo documento en el momento de la apertura, a diferencia de los existentes, y realizar una configuración específica.

- Controlar el procesamiento de las solicitudes para guardar, copiar o imprimir documentos o para combinar correspondencia.

- Recalcular la tabla de contenidos, los índices o las entradas de la tabla de un documento del escritos cuando se va a cerrar el documento.

- Importar los paquetes matemáticos de Python antes de abrir un documento Calc. Liberar estos paquetes cuando el documento se cierra.

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

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 monitorización 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

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.

Los eventos Iniciar aplicación y Cerrar aplicación pueden usarse, 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 cargarse y liberarse 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í

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,)

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

Temas relacionados

Creating Event Listeners

Importar módulos de Python

Creación de un controlador de diálogos

Ejemplos de programación en Python

Programar con secuencias de órdenes en Python

Llamar macros en Basic desde Python