diff --git a/source/text/sbasic/python/python_document_events.xhp b/source/text/sbasic/python/python_document_events.xhp index 21c6457c7e..be5cae32e0 100644 --- a/source/text/sbasic/python/python_document_events.xhp +++ b/source/text/sbasic/python/python_document_events.xhp @@ -10,7 +10,7 @@ --> - Python : Monitoring Document Events + Monitoring Document Events /text/sbasic/python/python_document_events.xhp @@ -26,13 +26,27 @@ API;lang.EventObject: Monitoring Document Event
-

Monitoring Document Events

-
+

Listening to Document Events

+ Listening to document events can help in the following situations: + + + Identify a new document at opening time, as opposed to existing ones, and perform a dedicated setup. + + + Control the processing of document save, document copy, print or mailmerge requests. + + + Recalculate table of contents, indexes or table entries of a Writer document when document is going to be closed + + + Import math Python packages before opening a Calc document. Release these packages when the document closes. + + Next to assigning macros to events, one can monitor events raised by %PRODUCTNAME documents. Application Programming Interface (API) broadcasters are responsible for calling event scripts. Unlike listeners that require to define all supported methods, even if unused, document monitors require only two methods next to hooked event scripts. -

Listening to Document Events

+ +

Monitoring Document Events

Monitoring is illustrated herewith for Basic and Python languages using object-oriented programming. Assigning OnLoad script, to the Open Document event, suffices to initiate and terminate document event monitoring. Tools - Customize menu Events tab is used to assign either scripts. Intercepting events helps setting scripts pre- and post-conditions such as loading and unloading libraries or track script processing in the background. Access2Base.Trace module usage is illustrating that second context. -

With Python

API;frame.Desktop: Monitoring Document Event @@ -150,41 +164,42 @@ Mind the misspelled documentEventOccured method that inherits a typo from %PRODUCTNAME Application Programming Interface (API). Start application and Close application events can respectively be used to set and to unset Python path for user scripts or %PRODUCTNAME scripts. In a similar fashion, document based Python libraries or modules can be loaded and released using Open document and Document closed events. Refer to Importing Python Modules for more information. -

With %PRODUCTNAME Basic

API;GlobalScope.BasicLibraries Tools;Strings - The Onload script is assigned to Open document event using Tools - Customize menu Events tab. Events monitoring starts from the moment a ConsoleLogger object is instantiated and ultimately stops when Basic engine releases it. OnLoad event loads necessary Basic libraries, while caught events are reported using Access2Base.Trace module. + Using Tools - Customize menu Events tab, the Open document event fires a ConsoleLogger initialisation. _documentEventOccured routine - set by ConsoleLogger - serves as a unique entry point to trap all document events. +

controller.Events module

+ + Option Explicit + + Global _obj As Object ' controller.ConsoleLogger instance + + Sub OnLoad(evt As com.sun.star.document.DocumentEvent) ' >> Open Document << + _obj = New ConsoleLogger : _obj.StartAdapter(evt) + End Sub ' controller.OnLoad + Sub _documentEventOccured(evt As com.sun.star.document.DocumentEvent) + ''' ConsoleLogger unique entry point ''' + _obj.DocumentEventOccurs(evt) + End Sub ' controller._documentEventOccured + +

controller.ConsoleLogger class module

+ Events monitoring starts from the moment a ConsoleLogger object is instantiated and ultimately stops upon document closure. StartAdapter routine loads necessary Basic libraries, while caught events are reported using Access2Base.Trace module. - REM controller.Events module - Option Explicit - Private _obj As Object ' controller.ConsoleLogger instance - - Sub OnLoad(evt As com.sun.star.document.DocumentEvent) ' >> Open Document << - _obj = New ConsoleLogger : _obj.Start(evt) - End Sub ' controller.OnLoad - ' ---- - REM controller.ConsoleLogger class module Option Explicit Option Compatible Option ClassModule ' ADAPTER design pattern object to be instantiated in the "Open Document" event Private Const UI_PROMPT = True - Private Const UI_NOPROMPT = False ' Set it to True to visualise documents events + Private Const UI_NOPROMPT = False ' Set it to True to visualise documents events - ' CONSTRUCTOR/DESTRUCTOR - Private Sub Class_Initialize() - End Sub ' controller.ConsoleLogger.Initialize - Private Sub Class_Terminate() - End Sub ' controller.ConsoleLogger.Terminate - ' MEMBERS Private _evtAdapter As Object ' com.sun.star.document.XDocumentEventBroadcaster + Private _txtMsg As String ' text message to log in console - ' PROPERTIES + ' PROPERTIES Private Property Get FileName As String ''' System-dependent filename ''' Const _LIBRARY = "Tools" : With GlobalScope.BasicLibraries @@ -194,46 +209,39 @@ End Property ' controller.ConsoleLogger.Filename ' METHODS - Private Sub _documentEventOccured(evt As com.sun.star.document.DocumentEvent) + Public Sub DocumentEventOccurs(evt As com.sun.star.document.DocumentEvent) ''' Monitor document events ''' Access2Base.Trace.TraceLog("DEBUG", _ evt.EventName &" in "& Filename(evt.Source.URL), _ UI_NOPROMPT) Select Case evt.EventName - Case "OnUnload" : _Stop(evt) + Case "OnUnload" : _StopAdapter(evt) End Select - End Sub ' controller.ConsoleLogger._documentEventOccured + End Sub ' controller.ConsoleLogger.DocumentEventOccurs - Private Sub _disposing(evt As com.sun.star.lang.EventObject) - End Sub ' controller.ConsoleLogger.disposing - - Public Sub Start(Optional evt As com.sun.star.document.DocumentEvent) + Public Sub StartAdapter(Optional evt As com.sun.star.document.DocumentEvent) ''' Initialize document events logging ''' Const _LIBRARY = "Access2Base" : With GlobalScope.BasicLibraries If Not .IsLibraryLoaded(_LIBRARY) Then .LoadLibrary(_LIBRARY) End With : Access2Base.Trace.TraceLevel("DEBUG") - Access2Base.Trace.TraceLog("INFO", _ - IIf(IsMissing(evt),"",evt.EventName & "-") & "Document events are being logged", _ - UI_PROMPT) - + If IsMissing(evt) Then _txtMsg = "" Else _txtMsg = evt.EventName & "-" + Access2Base.Trace.TraceLog("INFO", _txtMsg & "Document events are being logged", UI_PROMPT) _evtAdapter = CreateUnoListener( "_", "com.sun.star.document.XDocumentEventListener" ) ThisComponent.addDocumentEventListener( _evtAdapter ) - End Sub ' controller.ConsoleLogger.Start + End Sub ' controller.ConsoleLogger.StartAdapter - Private Sub _Stop(Optional evt As com.sun.star.document.DocumentEvent) + Private Sub _StopAdapter(Optional evt As com.sun.star.document.DocumentEvent) ''' Terminate document events logging ''' ThisComponent.removeDocumentEventListener( _evtAdapter ) - Access2Base.Trace.TraceLog("INFO", _ - IIf(IsMissing(evt),"",evt.EventName & "-") & "Document events have been logged", _ - UI_PROMPT) - Access2Base.Trace.TraceConsole() ' Captured events dialog - End Sub ' controller.ConsoleLogger._Stop + If IsMissing(evt) Then _txtMsg = "" Else _txtMsg = evt.EventName & "-" + Access2Base.Trace.TraceLog("INFO", _txtMsg & "Document events have been logged", UI_PROMPT) + Access2Base.Trace.TraceConsole() ' Captured events dialog + End Sub ' controller.ConsoleLogger._StopAdapter - ' EVENTS + ' EVENTS ' Your code for handled events goes here Mind the misspelled _documentEventOccured method that inherits a typo from %PRODUCTNAME Application Programming Interface (API). -

Discovering Documents Events

API;frame.GlobalEventBroadcaster: Monitoring Document Event @@ -282,4 +290,4 @@ - + \ No newline at end of file