source/text/sbasic/python/python_document_events.xhp | 98 ++++++++++---------
1 file changed, 53 insertions(+), 45 deletions(-)
New commits:
commit bd31d03c6aa4b3e8422b03b9947f96b36fc30c61
Author: Alain Romedenne <alain.romede...@libreoffice.org>
AuthorDate: Wed Sep 1 17:05:40 2021 +0200
Commit: Olivier Hallot <olivier.hal...@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.hal...@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
