source/text/sbasic/python/python_listener.xhp | 3
source/text/sbasic/shared/03132000.xhp | 159 ++++++++++++++++----------
2 files changed, 103 insertions(+), 59 deletions(-)
New commits:
commit b122dcc35b2015c8ffd0f826dd99edfeeebb39d1
Author: Alain Romedenne <alain.romede...@libreoffice.org>
AuthorDate: Fri Oct 21 10:23:30 2022 +0200
Commit: Alain Romedenne <alain.romede...@libreoffice.org>
CommitDate: Tue Oct 25 16:32:42 2022 +0200
tdf141474 CreateUnoListener function accepts keyword arguments
- literals and links added to improve page legibility
- 'related to' items added
- Multiple text clarifications and additionss
Change-Id: I0d7515783cb53f382ff2246a4a377ffb871a8284
Reviewed-on: https://gerrit.libreoffice.org/c/help/+/141578
Tested-by: Jenkins
Reviewed-by: Alain Romedenne <alain.romede...@libreoffice.org>
diff --git a/source/text/sbasic/python/python_listener.xhp
b/source/text/sbasic/python/python_listener.xhp
index 6cffde6a6c..c9f97398a8 100644
--- a/source/text/sbasic/python/python_listener.xhp
+++ b/source/text/sbasic/python/python_listener.xhp
@@ -155,7 +155,8 @@
<paragraph role="paragraph" id="N0499">Listeners are usually coded along
with <link href="text/sbasic/python/python_dialogs.xhp" name ="dialog
opening">dialog opening</link>. Numerous listener approaches are possible such
as event handlers for dialogs or event monitors for documents or
forms.</paragraph>
<section id="relatedtopics" >
<embed href="text/sbasic/guide/sample_code.xhp#sample_code"/>
- <paragraph role="paragraph" id="N0505"><link
href="text/sbasic/shared/03132000.xhp" name ="CreateUnoListener
Function">CreateUnoListener Function</link></paragraph>
+ <embed href="text/sbasic/shared/03132000.xhp#CreateUnoListener"/>
+ <embed href="text/swriter/01/05060700.xhp#"/>
<paragraph role="paragraph" id="N0506"><link
href="text/swriter/01/05060700.xhp" name ="Events mapping to objects">Events
mapping to objects</link></paragraph>
<paragraph role="paragraph" id="N0509">See also <link
href="text/sbasic/shared/01040000.xhp" name ="Document events">Document
events</link>, <link href="text/shared/02/01170202.xhp" name ="Form
events">Form events</link>.</paragraph>
<embed href="text/sbasic/python/python_handler.xhp#pythonhandler_h1"/>
diff --git a/source/text/sbasic/shared/03132000.xhp
b/source/text/sbasic/shared/03132000.xhp
index 475fd43331..5550f11981 100644
--- a/source/text/sbasic/shared/03132000.xhp
+++ b/source/text/sbasic/shared/03132000.xhp
@@ -27,105 +27,148 @@
<body>
-
<section id="createunolistener">
<bookmark xml-lang="en-US" branch="index" id="bm_id3155150">
<bookmark_value>CreateUnoListener function</bookmark_value>
</bookmark>
-
-<paragraph id="hd_id3155150" role="heading" level="1" xml-lang="en-US"><link
href="text/sbasic/shared/03132000.xhp" name="CreateUnoListener
Function">CreateUnoListener Function</link></paragraph>
+<h1 id="hd_id3155150" xml-lang="en-US"><variable id="CreateUnoListener"><link
href="text/sbasic/shared/03132000.xhp" name="CreateUnoListener
Function">CreateUnoListener Function</link></variable></h1>
<paragraph id="par_id3149346" role="paragraph" xml-lang="en-US">Creates a
Listener instance.</paragraph>
</section>
-<paragraph id="par_id3153681" role="paragraph" xml-lang="en-US">Many Uno
interfaces let you register listeners on a special listener interface. This
allows you to listen for specific events and call up the appropriate listener
method. The CreateUnoListener function waits for the called listener interface
and then passes the interface an object that the interface supports. This
object is then passed to the method to register the listener.</paragraph>
+<paragraph id="par_id3153681" role="paragraph" xml-lang="en-US">Many Uno
objects let you register listeners with dedicated listener interfaces. This
allows to listen for specific events and call up the appropriate listener
method. The <literal>CreateUnoListener</literal> function sets a listener
interface associated to an UNO object. The listener interface is then bound to
its associated object.</paragraph>
+
<embed href="text/sbasic/shared/00000003.xhp#functsyntax"/>
-<paragraph id="par_id3143228" role="code" xml-lang="en-US">oListener =
CreateUnoListener( Prefixname, ListenerInterfaceName )</paragraph>
+<bascode>
+ <paragraph role="bascode" id="bas_id681666359376854" localize="false">
CreateUnoListener( Prefix As String, Typename As String) As Object</paragraph>
+</bascode>
+<embed href="text/sbasic/shared/00000003.xhp#functparameters"/>
+<paragraph role="paragraph" id="par_id531666699350617"><emph>Prefix</emph>: A
text prefix used in BASIC subroutines that handle events.</paragraph>
+<paragraph role="paragraph" id="par_id281666699351161"><emph>Typename</emph>:
A fully qualified UNO listener interface name.</paragraph>
+<embed href="text/sbasic/shared/00000003.xhp#functvalue"/>
+<paragraph role="paragraph" id="par_id241666699584417">The UNO service
corresponding to the <literal>Typename</literal> listener interface name,
<literal>Null</literal> value otherwise.</paragraph>
<embed href="text/sbasic/shared/00000003.xhp#functexample"/>
-<paragraph id="par_id3154046" role="paragraph" xml-lang="en-US">The following
example is based on a Basic library object.</paragraph>
+<paragraph id="par_id3154046" role="paragraph" xml-lang="en-US">The following
example listens to events occuring for a BASIC library object.</paragraph>
<bascode>
-<paragraph id="par_idm1340547456" role="bascode" localize="false"
xml-lang="en-US">Dim oListener</paragraph>
+<paragraph id="par_idm1340547456" role="bascode" localize="false"
xml-lang="en-US">Dim oListener As Object</paragraph>
<paragraph id="par_idm1340546224" role="bascode" localize="false"
xml-lang="en-US">oListener = CreateUnoListener(
"ContListener_","com.sun.star.container.XContainerListener" )</paragraph>
</bascode>
-<paragraph id="par_id3149294" role="paragraph" xml-lang="en-US">The
CreateUnoListener method requires two parameters. The first is a prefix and is
explained in detail below. The second parameter is the fully qualified name of
the Listener interface that you want to use.</paragraph>
-<paragraph id="par_id3149670" role="paragraph" xml-lang="en-US">The Listener
must then be added to the Broadcaster Object. This is done by calling the
appropriate method for adding a Listener. These methods always follow the
pattern "addFooListener", where "Foo" is the Listener Interface Type, without
the 'X'. In this example, the addContainerListener method is called to register
the XContainerListener:</paragraph>
+<paragraph id="par_id3149294" role="paragraph" xml-lang="en-US">The
<literal>CreateUnoListener</literal> method requires two parameters. The first
is <emph>Prefix</emph> and is explained in detail below. <emph>Typename</emph>
second parameter is the fully qualified name of the listener
interface.</paragraph>
+<paragraph id="par_id3149670" role="paragraph" xml-lang="en-US">Every listener
must be registered to %PRODUCTNAME broadcaster feature. This is performed by
binding each listener to its associated object. Bind methods always follow the
pattern '<literal>add</literal>Foo<literal>Listener</literal>', where 'Foo' is
the object type of the listener interface, without the 'X'. In this example,
the <link
href="https://api.libreoffice.org/docs/idl/ref/interfacecom_1_1sun_1_1star_1_1container_1_1XContainer.html#a69e03a743cfa3e99935cac90b5f4e291";
name="com.sun.star.container.XContainer"><literal>addContainerListener</literal></link>
method is called to register the
<literal>XContainerListener</literal>:</paragraph>
<bascode>
-<paragraph id="par_idm1340540544" role="bascode" localize="false"
xml-lang="en-US">Dim oLib</paragraph>
+<paragraph id="par_idm1340540544" role="bascode" localize="false"
xml-lang="en-US">Dim oLib As Object</paragraph>
<paragraph id="par_id3154940" role="bascode" xml-lang="en-US">oLib =
BasicLibraries.Library1 ' Library1 must exist!</paragraph>
<paragraph id="par_id3150359" role="bascode"
xml-lang="en-US">oLib.addContainerListener( oListener ) ' Register the
listener</paragraph>
</bascode>
-<paragraph id="par_id3154138" role="paragraph" xml-lang="en-US">The Listener
is now registered. When an event occurs, the corresponding Listener calls the
appropriate method from the com.sun.star.container.XContainerListener
Interface.</paragraph>
-<paragraph id="par_id3148922" role="paragraph" xml-lang="en-US">The prefix
calls registered Listeners from Basic-subroutines. The Basic run-time system
searches for Basic-subroutines or functions that have the name
"PrefixListenerMethode" and calls them when found. Otherwise, a run-time error
occurs.</paragraph>
-<paragraph id="par_id3150768" role="paragraph" xml-lang="en-US">In this
example, the Listener-Interface uses the following methods:</paragraph>
+<paragraph id="par_id3154138" role="paragraph" xml-lang="en-US">The listener
is now registered. When an event occurs, the active listener calls the
appropriate method defined in <link
href="https://api.libreoffice.org/docs/idl/ref/interfacecom_1_1sun_1_1star_1_1container_1_1XContainerListener.html";
name="XContainerListener
interface">com.sun.star.container.XContainerListener</link>
interface.</paragraph>
-<list type="unordered">
- <listitem>
- <paragraph id="par_id3151176" role="listitem" xml-lang="en-US"
localize="false">disposing:</paragraph>
- </listitem>
- <listitem>
- <paragraph id="par_id3145173" role="listitem" xml-lang="en-US">Listener
base interface (com.sun.star.lang.XEventListener): base interface for all
Listener Interfaces</paragraph>
- </listitem>
- <listitem>
- <paragraph id="par_id3156212" role="listitem" xml-lang="en-US"
localize="false">elementInserted:</paragraph>
- </listitem>
- <listitem>
- <paragraph id="par_id3159254" role="listitem" xml-lang="en-US">Method of
the com.sun.star.container.XContainerListener interface</paragraph>
- </listitem>
- <listitem>
- <paragraph id="par_id3147287" role="listitem" xml-lang="en-US"
localize="false">elementRemoved:</paragraph>
- </listitem>
- <listitem>
- <paragraph id="par_id3146119" role="listitem" xml-lang="en-US">Method of
the com.sun.star.container.XContainerListener interface</paragraph>
- </listitem>
- <listitem>
- <paragraph id="par_id3153951" role="listitem" xml-lang="en-US"
localize="false">elementReplaced:</paragraph>
- </listitem>
- <listitem>
- <paragraph id="par_id3154013" role="listitem" xml-lang="en-US">Method of
the com.sun.star.container.XContainerListener interface</paragraph>
- </listitem></list>
-<paragraph id="par_id3147435" role="paragraph" xml-lang="en-US">In this
example, the prefix is ContListener_. The following subroutines must therefore
be implemented in Basic:</paragraph>
+ <paragraph id="par_id3148922" role="paragraph" xml-lang="en-US">Event-driven
registered BASIC subroutines require to use a defined <emph>Prefix</emph>. The
BASIC run-time system searches for subroutines or functions that have the name
'Prefix+ListenerMethod' and calls them when found. Otherwise, a run-time error
occurs.</paragraph>
+<paragraph id="par_id3150768" role="paragraph" xml-lang="en-US">In this
example, <link
href="https://api.libreoffice.org/docs/idl/ref/interfacecom_1_1sun_1_1star_1_1container_1_1XContainerListener-members.html";
name="container.XContainerListener">com.sun.star.container.XContainerListener</link>
interface defines the following methods:</paragraph>
+<table id="tab_id591666342054257">
+ <tablerow>
+ <tablecell>
+ <paragraph id="par_id701666342054257"
role="tablehead">method</paragraph>
+ </tablecell>
+ <tablecell>
+ <paragraph id="par_id531666342054257"
role="tablehead">description</paragraph>
+ </tablecell>
+ </tablerow>
+ <tablerow>
+ <tablecell>
+ <paragraph id="par_id11666342054257"
role="tablecontent"><literal>disposing</literal></paragraph>
+ </tablecell>
+ <tablecell>
+ <paragraph id="par_id841666342054257" role="tablecontent"><link
href="https://api.libreoffice.org/docs/idl/ref/interfacecom_1_1sun_1_1star_1_1lang_1_1XEventListener.html";
name="lang.XEventListener">com.sun.star.lang.XEventListener</link> base
interface for all Listener Interfaces</paragraph>
+ </tablecell>
+ </tablerow>
+ <tablerow>
+ <tablecell>
+ <paragraph id="par_id11666342054258"
role="tablecontent"><literal>elementInserted</literal></paragraph>
+ </tablecell>
+ <tablecell>
+ <paragraph id="par_id841666342054258" role="tablecontent">Method of
the <link
href="https://api.libreoffice.org/docs/idl/ref/interfacecom_1_1sun_1_1star_1_1container_1_1XContainerListener-members.html";
name="container.XContainerListener">com.sun.star.container.XContainerListener</link>
interface</paragraph>
+ </tablecell>
+ </tablerow>
+ <tablerow>
+ <tablecell>
+ <paragraph id="par_id11666342054259"
role="tablecontent">elementRemoved</paragraph>
+ </tablecell>
+ <tablecell>
+ <paragraph id="par_id841666342054259" role="tablecontent">Method of
the <link
href="https://api.libreoffice.org/docs/idl/ref/interfacecom_1_1sun_1_1star_1_1container_1_1XContainerListener-members.html";
name="container.XContainerListener">com.sun.star.container.XContainerListener</link>
interface</paragraph>
+ </tablecell>
+ </tablerow>
+ <tablerow>
+ <tablecell>
+ <paragraph id="par_id11666342054267"
role="tablecontent">elementReplaced</paragraph>
+ </tablecell>
+ <tablecell>
+ <paragraph id="par_id841666342054267" role="tablecontent">Method of
the <link
href="https://api.libreoffice.org/docs/idl/ref/interfacecom_1_1sun_1_1star_1_1container_1_1XContainerListener-members.html";
name="container.XContainerListener">com.sun.star.container.XContainerListener</link>
interface</paragraph>
+ </tablecell>
+ </tablerow>
+</table>
+
+<paragraph id="par_id3147435" role="paragraph"
xml-lang="en-US">'ContListener_' used in this example implies that the
following subroutines must be implemented in BASIC:</paragraph>
<list type="unordered">
<listitem>
- <paragraph id="par_id3155411" role="listitem" xml-lang="en-US"
localize="false">ContListener_disposing</paragraph>
+ <paragraph id="par_id3155411" role="listitem" xml-lang="en-US"
localize="false">ContListener_<literal>disposing</literal></paragraph>
</listitem>
<listitem>
- <paragraph id="par_id3146923" role="listitem" xml-lang="en-US"
localize="false">ContListener_elementInserted</paragraph>
+ <paragraph id="par_id3146923" role="listitem" xml-lang="en-US"
localize="false">ContListener_<literal>elementInserted</literal></paragraph>
</listitem>
<listitem>
- <paragraph id="par_id3147318" role="listitem" xml-lang="en-US"
localize="false">ContListener_elementRemoved</paragraph>
+ <paragraph id="par_id3147318" role="listitem" xml-lang="en-US"
localize="false">ContListener_<literal>elementRemoved</literal></paragraph>
</listitem>
<listitem>
- <paragraph id="par_id3152578" role="listitem" xml-lang="en-US"
localize="false">ContListener_elementReplaced</paragraph>
+ <paragraph id="par_id3152578" role="listitem" xml-lang="en-US"
localize="false">ContListener_<literal>elementReplaced</literal></paragraph>
</listitem></list>
-<paragraph id="par_id3150592" role="paragraph" xml-lang="en-US">An event
structure type that contains information about an event exists for every
Listener type. When a Listener method is called, an instance of this event is
passed to the method as a parameter. Basic Listener methods can also call these
event objects, so long as the appropriate parameter is passed in the Sub
declaration. For example:</paragraph>
+<paragraph id="par_id3150592" role="paragraph" xml-lang="en-US">Every listener
interface defines a set of controlled event names associated to Uno objects.
When an event occurs, it is sent to the method as a parameter. BASIC event
methods can also call one another, as long as the appropriate parameter is
passed in the <literal>Sub</literal> declaration. For example:</paragraph>
<bascode>
-<paragraph id="par_idm1340499136" role="bascode" localize="false"
xml-lang="en-US">Sub ContListener_disposing( oEvent )</paragraph>
+<paragraph id="par_idm1340499136" role="bascode" localize="false"
xml-lang="en-US">Sub ContListener_disposing( oEvent As
com.sun.star.lang.EventObject )</paragraph>
<paragraph id="par_id31538768025" role="bascode" localize="false"
xml-lang="en-US"> MsgBox "disposing"</paragraph>
-<paragraph id="par_idm1340496176" role="bascode" localize="false"
xml-lang="en-US"> MsgBox oEvent.Dbg_Properties</paragraph>
<paragraph id="par_idm1340684736" role="bascode" localize="false"
xml-lang="en-US">End Sub</paragraph>
<paragraph id="par_idm1340683504" role="bascode" localize="false"
xml-lang="en-US"> </paragraph>
-<paragraph id="par_idm1340682256" role="bascode" localize="false"
xml-lang="en-US">Sub ContListener_elementInserted( oEvent )</paragraph>
-<paragraph id="par_id31540984458" role="bascode" localize="false"
xml-lang="en-US"> MsgBox "elementInserted"</paragraph>
-<paragraph id="par_idm1340679264" role="bascode" localize="false"
xml-lang="en-US"> MsgBox oEvent.Dbg_Properties</paragraph>
+<paragraph id="par_idm1340682256" role="bascode" localize="false"
xml-lang="en-US">Sub ContListener_elementInserted( oEvent As
com.sun.star.container.ContainerEvent )</paragraph>
+<paragraph id="par_id31540984458" role="bascode" localize="false"
xml-lang="en-US"> MsgBox oEvent.Source.' "elementInserted"</paragraph>
<paragraph id="par_idm1340678016" role="bascode" localize="false"
xml-lang="en-US">End Sub</paragraph>
<paragraph id="par_idm1340676784" role="bascode" localize="false"
xml-lang="en-US"> </paragraph>
-<paragraph id="par_idm1340675584" role="bascode" localize="false"
xml-lang="en-US">Sub ContListener_elementRemoved( oEvent )</paragraph>
+<paragraph id="par_idm1340675584" role="bascode" localize="false"
xml-lang="en-US">Sub ContListener_elementRemoved( oEvent As
com.sun.star.container.ContainerEvent )</paragraph>
<paragraph id="par_id31539470236" role="bascode" localize="false"
xml-lang="en-US"> MsgBox "elementRemoved"</paragraph>
-<paragraph id="par_idm1340672544" role="bascode" localize="false"
xml-lang="en-US"> MsgBox oEvent.Dbg_Properties</paragraph>
<paragraph id="par_idm1340671296" role="bascode" localize="false"
xml-lang="en-US">End Sub</paragraph>
<paragraph id="par_idm1340670064" role="bascode" localize="false"
xml-lang="en-US"> </paragraph>
-<paragraph id="par_idm1340668864" role="bascode" localize="false"
xml-lang="en-US">Sub ContListener_elementReplaced( oEvent )</paragraph>
+<paragraph id="par_idm1340668864" role="bascode" localize="false"
xml-lang="en-US">Sub ContListener_elementReplaced( oEvent As
com.sun.star.container.ContainerEvent )</paragraph>
<paragraph id="par_id31489150148" role="bascode" localize="false"
xml-lang="en-US"> MsgBox "elementReplaced"</paragraph>
-<paragraph id="par_idm1340665824" role="bascode" localize="false"
xml-lang="en-US"> MsgBox oEvent.Dbg_Properties</paragraph>
<paragraph id="par_idm1340664576" role="bascode" localize="false"
xml-lang="en-US">End Sub</paragraph>
</bascode>
-<paragraph id="par_id3156056" role="paragraph" xml-lang="en-US">You do not
need to include the parameter of an event object if the object is not
used:</paragraph>
+<paragraph id="par_id3156056" role="paragraph" xml-lang="en-US">Not need to
include the event object parameter when not used:</paragraph>
<bascode>
<paragraph id="par_id3150042" role="bascode" xml-lang="en-US">' Minimal
implementation of Sub disposing</paragraph>
-<paragraph id="par_idm1340659344" role="bascode" localize="false"
xml-lang="en-US">Sub ContListener_disposing</paragraph>
-<paragraph id="par_idm1340658096" role="bascode" localize="false"
xml-lang="en-US">End Sub</paragraph>
+<paragraph id="par_idm1340659344" role="bascode" localize="false">Sub
ContListener_disposing</paragraph>
+<paragraph id="par_idm1340658096" role="bascode" localize="false">End
Sub</paragraph>
+</bascode>
+<warning id="par_id621666343214282" xml-lang="en-US">Listener methods must
<emph>always</emph> be implemented to avoid BASIC run-time errors.</warning>
+<tip id="par_id101666620765251">Use <link
href="text/sbasic/shared/03/sf_exception.xhp"
name="ScriptForge"><literal>ScriptForge</literal></link> library console when
the BASIC IDE is not easily accessible, that is during events processing. Use
the <link href="text/sbasic/shared/03/sf_exception.xhp#DebugPrint"
name="DebugPrint"><literal>DebugPrint</literal></link> method to add any
relevant information to the console. Console entries can be dumped to a text
file or visualized in a dialog window. Use <literal>Trace</literal> module of
<link href="text/sbasic/guide/access2base.xhp" name="Access2Base
library"><literal>Access2Base</literal></link> library as an alternative</tip>
+<bascode>
+ <paragraph role="bascode" id="bas_id871666620966333">Sub
SF_Trace</paragraph>
+ <paragraph role="bascode" id="bas_id361666620966645">
GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")</paragraph>
+ <paragraph role="bascode" id="bas_id391666620966798"> svc =
CreateScriptService("ScriptForge.Exception")</paragraph>
+ <paragraph role="bascode" id="bas_id821666620967245"> svc.Console
modal:=False</paragraph>
+ <paragraph role="bascode" id="bas_id741666621069519">
svc.DebugPrint("Lorem", "Ipsum", "...")</paragraph>
+ <paragraph role="bascode" id="bas_id771666620967685">End Sub '
SF_Trace</paragraph>
+ <paragraph role="bascode" id="bas_id451666683735574"></paragraph>
+ <paragraph role="bascode" id="bas_id261666683736832">Sub
A2B_Trace</paragraph>
+ <paragraph role="bascode" id="bas_id61666683737033">
GlobalScope.BasicLibraries.LoadLibrary("Access2Base")</paragraph>
+ <paragraph role="bascode" id="bas_id301666683737232">
Access2Base.Trace.DebugPrint("Lorem", "Ipsum", "...")</paragraph>
+ <paragraph role="bascode" id="bas_id561666683737419">
Access2Base.Trace.TraceConsole()</paragraph>
+ <paragraph role="bascode" id="bas_id251666683738645">End Sub '
A2B_Trace</paragraph>
</bascode>
-<paragraph id="par_id3150940" role="warning" xml-lang="en-US">Listener methods
must <emph>always</emph> be implemented to avoid Basic run-time
errors.</paragraph>
-</body>
+ <section id="relatedtopics" >
+ <embed href="text/sbasic/python/python_listener.xhp#pythonlistener"/>
+ <paragraph role="paragraph" id="N0506"><link
href="text/swriter/01/05060700.xhp" name ="Events mapping to objects">Events
mapping to objects</link></paragraph>
+ <paragraph role="paragraph" id="N0509">See also <link
href="text/sbasic/shared/01040000.xhp" name ="Document events">Document
events</link>, <link href="text/shared/02/01170202.xhp" name ="Form
events">Form events</link>.</paragraph>
+ <embed href="text/sbasic/python/python_handler.xhp#pythonhandler_h1"/>
+ <embed
href="text/sbasic/python/python_document_events.xhp#pythonmonitor"/>
+ </section>
+
+</body>
</helpdocument>
