[Libreoffice-commits] help.git: source/text
Alain Romedenne (via logerrit)
logerrit at kemper.freedesktop.org
Fri Sep 3 23:16:30 UTC 2021
source/text/sbasic/python/python_document_events.xhp | 98 ++++++++++---------
1 file changed, 53 insertions(+), 45 deletions(-)
New commits:
commit bd31d03c6aa4b3e8422b03b9947f96b36fc30c61
Author: Alain Romedenne <alain.romedenne at libreoffice.org>
AuthorDate: Wed Sep 1 17:05:40 2021 +0200
Commit: Olivier Hallot <olivier.hallot at libreoffice.org>
CommitDate: Sat Sep 4 01:16:11 2021 +0200
Fix in Basic macro example
Change-Id: Ia73865f59fc5b605853b5c1ff6232349fd186771
Reviewed-on: https://gerrit.libreoffice.org/c/help/+/121456
Tested-by: Jenkins
Reviewed-by: Olivier Hallot <olivier.hallot at libreoffice.org>
diff --git a/source/text/sbasic/python/python_document_events.xhp b/source/text/sbasic/python/python_document_events.xhp
index 21c6457c7..be5cae32e 100644
--- a/source/text/sbasic/python/python_document_events.xhp
+++ b/source/text/sbasic/python/python_document_events.xhp
@@ -10,7 +10,7 @@
-->
<meta>
<topic id="text/sbasic/python/python_document_events">
- <title id="tit" xml-lang="en-US">Python : Monitoring Document Events</title>
+ <title id="tit" xml-lang="en-US">Monitoring Document Events</title>
<filename>/text/sbasic/python/python_document_events.xhp</filename>
</topic>
</meta>
@@ -26,13 +26,27 @@
<bookmark_value>API;lang.EventObject: Monitoring Document Event</bookmark_value>
</bookmark>
<section id="pythonmonitor1">
- <h1 id="N0527"><variable id="pythonmonitor"><link href="text/sbasic/python/python_document_events.xhp" name="Monitoring Document Events">Monitoring Document Events</link></variable></h1>
- </section>
+ <h1 id="N0527"><variable id="pythonmonitor"><link href="text/sbasic/python/python_document_events.xhp" name="Monitoring Document Events">Listening to Document Events</link></variable></h1>
+ <paragraph role="paragraph" id="par_id641630582314861">Listening to document events can help in the following situations:</paragraph>
+ <list type="unordered">
+ <listitem>
+ <paragraph id="par_id431630582396327" role="listitem">Identify a new document at opening time, as opposed to existing ones, and perform a dedicated setup.</paragraph>
+ </listitem>
+ <listitem>
+ <paragraph id="par_id461630582396782" role="listitem">Control the processing of document save, document copy, print or mailmerge requests.</paragraph>
+ </listitem>
+ <listitem>
+ <paragraph id="par_id631630582394790" role="listitem">Recalculate table of contents, indexes or table entries of a Writer document when document is going to be closed</paragraph>
+ </listitem>
+ <listitem>
+ <paragraph id="par_id601630582398998" role="listitem">Import math Python packages before opening a Calc document. Release these packages when the document closes.</paragraph>
+ </listitem>
+ </list>
<paragraph role="paragraph" id="N0528">Next to <link href="text/sbasic/shared/01040000.xhp" name ="assigning macros to events">assigning macros to events</link>, 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.</paragraph>
- <h2 id="N0529">Listening to Document Events</h2>
+ </section>
+ <h2 id="N0529">Monitoring Document Events</h2>
<paragraph role="paragraph" id="N0530">Monitoring is illustrated herewith for Basic and Python languages using object-oriented programming. Assigning <literal>OnLoad</literal> script, to the <emph>Open Document</emph> event, suffices to initiate and terminate document event monitoring. <menuitem>Tools - Customize</menuitem> menu <menuitem>Events</menuitem> tab is used to assign either scripts.</paragraph>
<paragraph role="paragraph" id="N0531">Intercepting events helps setting scripts pre- and post-conditions such as loading and unloading libraries or track script processing in the background. <literal>Access2Base.Trace</literal> module usage is illustrating that second context.</paragraph>
-
<h3 id="N0532">With Python</h3>
<bookmark xml-lang="en-US" branch="index" id="bm_id721622446590963">
<bookmark_value>API;frame.Desktop: Monitoring Document Event</bookmark_value>
@@ -150,41 +164,42 @@
</pycode>
<warning id="N0647">Mind the misspelled <literal>documentEventOccured</literal> method that inherits a typo from %PRODUCTNAME Application Programming Interface (API).</warning>
<paragraph role="tip" id="N0648"><emph>Start application</emph> and <emph>Close application</emph> 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 <emph>Open document</emph> and <emph>Document closed</emph> events. Refer to <link href="text/sbasic/python/python_import.xhp" name ="Importing Python Modules">Importing Python Modules</link> for more information.</paragraph>
-
<h3 id="N0649">With %PRODUCTNAME Basic</h3>
<bookmark xml-lang="en-US" branch="index" id="bm_id591622446367707">
<bookmark_value>API;GlobalScope.BasicLibraries</bookmark_value>
<bookmark_value>Tools;Strings</bookmark_value>
</bookmark>
- <paragraph role="paragraph" id="N0650">The <literal>Onload</literal> script is assigned to <emph>Open document</emph> event using <menuitem>Tools - Customize</menuitem> menu <menuitem>Events</menuitem> tab. Events monitoring starts from the moment a <literal>ConsoleLogger</literal> object is instantiated and ultimately stops when Basic engine releases it. <literal>OnLoad</literal> event loads necessary Basic libraries, while caught events are reported using <literal>Access2Base.Trace</literal> module.</paragraph>
+ <paragraph role="paragraph" id="N0650">Using <menuitem>Tools - Customize</menuitem> menu <menuitem>Events</menuitem> tab, the <menuitem>Open document</menuitem> event fires a <literal>ConsoleLogger</literal> initialisation. <literal>_documentEventOccured</literal> routine - set by <literal>ConsoleLogger</literal> - serves as a unique entry point to trap all document events.</paragraph>
+ <h4 id="hd_id421630510141729">controller.Events module</h4>
+ <bascode>
+ <paragraph role="bascode" localize="false" id="bas_id591630567376295">Option Explicit</paragraph>
+ <paragraph role="bascode" localize="false" id="bas_id101630567377583"></paragraph>
+ <paragraph role="bascode" xml-lang="en-US" id="bas_id431630567378062">Global _obj As Object ' controller.ConsoleLogger instance</paragraph>
+ <paragraph role="bascode" localize="false" id="bas_id971630567378798"></paragraph>
+ <paragraph role="bascode" xml-lang="en-US" id="N0655">Sub OnLoad(evt As com.sun.star.document.DocumentEvent) ' >> Open Document <<</paragraph>
+ <paragraph role="bascode" localize="false" id="N0656"> _obj = New ConsoleLogger : _obj.StartAdapter(evt)</paragraph>
+ <paragraph role="bascode" localize="false" id="N0657">End Sub ' controller.OnLoad</paragraph>
+ <paragraph role="bascode" localize="false" id="bas_id201630509594858">Sub _documentEventOccured(evt As com.sun.star.document.DocumentEvent)</paragraph>
+ <paragraph role="bascode" xml-lang="en-US" id="bas_id371630509596674"> ''' ConsoleLogger unique entry point '''</paragraph>
+ <paragraph role="bascode" localize="false" id="bas_id551630509597227"> _obj.DocumentEventOccurs(evt)</paragraph>
+ <paragraph role="bascode" localize="false" id="bas_id511630509597425">End Sub ' controller._documentEventOccured</paragraph>
+ </bascode>
+ <h4 id="hd_id721630511986813">controller.ConsoleLogger class module</h4>
+ <paragraph role="paragraph" id="par_id901630509435225">Events monitoring starts from the moment a <literal>ConsoleLogger</literal> object is instantiated and ultimately stops upon document closure. <literal>StartAdapter</literal> routine loads necessary Basic libraries, while caught events are reported using <literal>Access2Base.Trace</literal> module.</paragraph>
<bascode>
- <paragraph role="bascode" xml-lang="en-US" id="N0651">REM controller.Events module</paragraph>
- <paragraph role="bascode" localize="false" id="N0652">Option Explicit</paragraph>
- <paragraph role="bascode" xml-lang="en-US" id="N0653">Private _obj As Object ' controller.ConsoleLogger instance</paragraph>
- <paragraph role="bascode" localize="false" id="N0654"> </paragraph>
- <paragraph role="bascode" xml-lang="en-US" id="N0655">Sub OnLoad(evt As com.sun.star.document.DocumentEvent) ' >> Open Document <<</paragraph>
- <paragraph role="bascode" localize="false" id="N0656"> _obj = New ConsoleLogger : _obj.Start(evt)</paragraph>
- <paragraph role="bascode" localize="false" id="N0657">End Sub ' controller.OnLoad</paragraph>
- <paragraph role="bascode" localize="false" id="N0658">' ----</paragraph>
- <paragraph role="bascode" xml-lang="en-US" id="N0659">REM controller.ConsoleLogger class module</paragraph>
<paragraph role="bascode" localize="false" id="N0660">Option Explicit</paragraph>
<paragraph role="bascode" localize="false" id="N0661">Option Compatible</paragraph>
<paragraph role="bascode" localize="false" id="N0662">Option ClassModule</paragraph>
<paragraph role="bascode" localize="false" id="N0663"> </paragraph>
<paragraph role="bascode" xml-lang="en-US" id="N0664">' ADAPTER design pattern object to be instantiated in the "Open Document" event</paragraph>
<paragraph role="bascode" localize="false" id="N0665">Private Const UI_PROMPT = True</paragraph>
- <paragraph role="bascode" localize="false" id="N0666">Private Const UI_NOPROMPT = False ' Set it to True to visualise documents events</paragraph>
+ <paragraph role="bascode" xml-lang="en-US" id="N0666">Private Const UI_NOPROMPT = False ' Set it to True to visualise documents events</paragraph>
<paragraph role="bascode" localize="false" id="N0667"> </paragraph>
- <paragraph role="bascode" xml-lang="en-US" id="N0668">' CONSTRUCTOR/DESTRUCTOR</paragraph>
- <paragraph role="bascode" localize="false" id="N0669">Private Sub Class_Initialize()</paragraph>
- <paragraph role="bascode" localize="false" id="N0670">End Sub ' controller.ConsoleLogger.Initialize</paragraph>
- <paragraph role="bascode" localize="false" id="N0671">Private Sub Class_Terminate()</paragraph>
- <paragraph role="bascode" localize="false" id="N0672">End Sub ' controller.ConsoleLogger.Terminate</paragraph>
- <paragraph role="bascode" localize="false" id="N0673"> </paragraph>
<paragraph role="bascode" xml-lang="en-US" id="N0674">' MEMBERS</paragraph>
<paragraph role="bascode" localize="false" id="N0675">Private _evtAdapter As Object ' com.sun.star.document.XDocumentEventBroadcaster</paragraph>
+ <paragraph role="bascode" xml-lang="en-US" id="bas_id131630510956418">Private _txtMsg As String ' text message to log in console</paragraph>
<paragraph role="bascode" localize="false" id="N0676"> </paragraph>
- <paragraph role="bascode" localize="false" id="N0677">' PROPERTIES</paragraph>
+ <paragraph role="bascode" xml-lang="en-US" id="N0677">' PROPERTIES</paragraph>
<paragraph role="bascode" localize="false" id="N0678">Private Property Get FileName As String</paragraph>
<paragraph role="bascode" xml-lang="en-US" id="N0679"> ''' System-dependent filename '''</paragraph>
<paragraph role="bascode" localize="false" id="N0680"> Const _LIBRARY = "Tools" : With GlobalScope.BasicLibraries</paragraph>
@@ -194,46 +209,39 @@
<paragraph role="bascode" localize="false" id="N0684">End Property ' controller.ConsoleLogger.Filename</paragraph>
<paragraph role="bascode" localize="false" id="N0685"> </paragraph>
<paragraph role="bascode" xml-lang="en-US" id="N0686">' METHODS</paragraph>
- <paragraph role="bascode" localize="false" id="N0687">Private Sub _documentEventOccured(evt As com.sun.star.document.DocumentEvent)</paragraph>
+ <paragraph role="bascode" localize="false" id="N0687">Public Sub DocumentEventOccurs(evt As com.sun.star.document.DocumentEvent)</paragraph>
<paragraph role="bascode" xml-lang="en-US" id="N0688"> ''' Monitor document events '''</paragraph>
<paragraph role="bascode" localize="false" id="N0689"> Access2Base.Trace.TraceLog("DEBUG", _</paragraph>
<paragraph role="bascode" localize="false" id="N0690"> evt.EventName &" in "& Filename(evt.Source.URL), _</paragraph>
<paragraph role="bascode" localize="false" id="N0691"> UI_NOPROMPT)</paragraph>
<paragraph role="bascode" localize="false" id="N0692"> Select Case evt.EventName</paragraph>
- <paragraph role="bascode" localize="false" id="N0693"> Case "OnUnload" : _Stop(evt)</paragraph>
+ <paragraph role="bascode" localize="false" id="N0693"> Case "OnUnload" : _StopAdapter(evt)</paragraph>
<paragraph role="bascode" localize="false" id="N0694"> End Select</paragraph>
- <paragraph role="bascode" localize="false" id="N0695">End Sub ' controller.ConsoleLogger._documentEventOccured</paragraph>
+ <paragraph role="bascode" localize="false" id="N0695">End Sub ' controller.ConsoleLogger.DocumentEventOccurs</paragraph>
<paragraph role="bascode" localize="false" id="N0696"> </paragraph>
- <paragraph role="bascode" localize="false" id="N0697">Private Sub _disposing(evt As com.sun.star.lang.EventObject)</paragraph>
- <paragraph role="bascode" localize="false" id="N0698">End Sub ' controller.ConsoleLogger.disposing</paragraph>
- <paragraph role="bascode" localize="false" id="N0699"> </paragraph>
- <paragraph role="bascode" localize="false" id="N0700">Public Sub Start(Optional evt As com.sun.star.document.DocumentEvent)</paragraph>
+ <paragraph role="bascode" localize="false" id="N0700">Public Sub StartAdapter(Optional evt As com.sun.star.document.DocumentEvent)</paragraph>
<paragraph role="bascode" xml-lang="en-US" id="N0701"> ''' Initialize document events logging '''</paragraph>
<paragraph role="bascode" localize="false" id="N0702"> Const _LIBRARY = "Access2Base" : With GlobalScope.BasicLibraries</paragraph>
<paragraph role="bascode" localize="false" id="N0703"> If Not .IsLibraryLoaded(_LIBRARY) Then .LoadLibrary(_LIBRARY)</paragraph>
<paragraph role="bascode" localize="false" id="N0704"> End With : Access2Base.Trace.TraceLevel("DEBUG")</paragraph>
- <paragraph role="bascode" localize="false" id="N0705"> Access2Base.Trace.TraceLog("INFO", _</paragraph>
- <paragraph role="bascode" xml-lang="en-US" id="N0706"> IIf(IsMissing(evt),"",evt.EventName & "-") & "Document events are being logged", _</paragraph>
- <paragraph role="bascode" localize="false" id="N0707"> UI_PROMPT)</paragraph>
- <paragraph role="bascode" localize="false" id="N0708"> </paragraph>
+ <paragraph role="bascode" id="bas_id211630511166427"> If IsMissing(evt) Then _txtMsg = "" Else _txtMsg = evt.EventName & "-"</paragraph>
+ <paragraph role="bascode" xml-lang="en-US" id="N0705"> Access2Base.Trace.TraceLog("INFO", _txtMsg & "Document events are being logged", UI_PROMPT)</paragraph>
<paragraph role="bascode" localize="false" id="N0709"> _evtAdapter = CreateUnoListener( "_", "com.sun.star.document.XDocumentEventListener" )</paragraph>
<paragraph role="bascode" localize="false" id="N0710"> ThisComponent.addDocumentEventListener( _evtAdapter )</paragraph>
- <paragraph role="bascode" localize="false" id="N0711">End Sub ' controller.ConsoleLogger.Start</paragraph>
+ <paragraph role="bascode" localize="false" id="N0711">End Sub ' controller.ConsoleLogger.StartAdapter</paragraph>
<paragraph role="bascode" localize="false" id="N0712"> </paragraph>
- <paragraph role="bascode" localize="false" id="N0713">Private Sub _Stop(Optional evt As com.sun.star.document.DocumentEvent)</paragraph>
+ <paragraph role="bascode" localize="false" id="N0713">Private Sub _StopAdapter(Optional evt As com.sun.star.document.DocumentEvent)</paragraph>
<paragraph role="bascode" xml-lang="en-US" id="N0714"> ''' Terminate document events logging '''</paragraph>
<paragraph role="bascode" localize="false" id="N0715"> ThisComponent.removeDocumentEventListener( _evtAdapter )</paragraph>
- <paragraph role="bascode" localize="false" id="N0716"> Access2Base.Trace.TraceLog("INFO", _</paragraph>
- <paragraph role="bascode" xml-lang="en-US" id="N0717"> IIf(IsMissing(evt),"",evt.EventName & "-") & "Document events have been logged", _</paragraph>
- <paragraph role="bascode" localize="false" id="N0718"> UI_PROMPT)</paragraph>
- <paragraph role="bascode" localize="false" id="N0719"> Access2Base.Trace.TraceConsole() ' Captured events dialog</paragraph>
- <paragraph role="bascode" localize="false" id="N0720">End Sub ' controller.ConsoleLogger._Stop</paragraph>
+ <paragraph role="bascode" localize="false" id="N0716"> If IsMissing(evt) Then _txtMsg = "" Else _txtMsg = evt.EventName & "-"</paragraph>
+ <paragraph role="bascode" xml-lang="en-US" id="N0717"> Access2Base.Trace.TraceLog("INFO", _txtMsg & "Document events have been logged", UI_PROMPT)</paragraph>
+ <paragraph role="bascode" xml-lang="en-US" id="N0719"> Access2Base.Trace.TraceConsole() ' Captured events dialog</paragraph>
+ <paragraph role="bascode" localize="false" id="N0720">End Sub ' controller.ConsoleLogger._StopAdapter</paragraph>
<paragraph role="bascode" localize="false" id="N0721"> </paragraph>
- <paragraph role="bascode" localize="false" id="N0722">' EVENTS</paragraph>
+ <paragraph role="bascode" xml-lang="en-US" id="N0722">' EVENTS</paragraph>
<paragraph role="bascode" xml-lang="en-US" id="N0723">' Your code for handled events goes here</paragraph>
</bascode>
<warning id="N0724">Mind the misspelled <literal>_documentEventOccured</literal> method that inherits a typo from %PRODUCTNAME Application Programming Interface (API).</warning>
-
<h2 id="N0725">Discovering Documents Events</h2>
<bookmark xml-lang="en-US" branch="index" id="bm_id681622445958242">
<bookmark_value>API;frame.GlobalEventBroadcaster: Monitoring Document Event</bookmark_value>
@@ -282,4 +290,4 @@
<embed href="text/sbasic/python/python_2_basic.xhp#py2ba_h1"/>
</section>
</body>
-</helpdocument>
+</helpdocument>
\ No newline at end of file
More information about the Libreoffice-commits
mailing list