1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
|
<?xml version="1.0" encoding="UTF-8"?>
<helpdocument version="1.0">
<!--
* This file is part of the LibreOffice project.
*
* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at http://mozilla.org/MPL/2.0/.
*
* This file incorporates work covered by the following license notice:
*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed
* with this work for additional information regarding copyright
* ownership. The ASF licenses this file to you under the Apache
* License, Version 2.0 (the "License"); you may not use this file
* except in compliance with the License. You may obtain a copy of
* the License at http://www.apache.org/licenses/LICENSE-2.0 .
-->
<meta>
<topic id="textsbasicshared03132000xml" indexer="include" status="PUBLISH">
<title id="tit" xml-lang="en-US">CreateUnoListener Function</title>
<filename>/text/sbasic/shared/03132000.xhp</filename>
</topic>
</meta>
<body>
<section id="createunolistener">
<bookmark xml-lang="en-US" branch="index" id="bm_id3155150">
<bookmark_value>CreateUnoListener function</bookmark_value>
</bookmark>
<h1 id="hd_id3155150" xml-lang="en-US"><variable id="CreateUnoListener"><link href="text/sbasic/shared/03132000.xhp">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 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"/>
<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 listens to events occurring for a BASIC library object.</paragraph>
<bascode>
<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 <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"><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 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 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">com.sun.star.container.XContainerListener</link> interface.</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">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">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">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">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">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_<literal>disposing</literal></paragraph>
</listitem>
<listitem>
<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_<literal>elementRemoved</literal></paragraph>
</listitem>
<listitem>
<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">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 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_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 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 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_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 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_idm1340664576" role="bascode" localize="false" xml-lang="en-US">End Sub</paragraph>
</bascode>
<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">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"><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"><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"><literal>Access2Base</literal></link> library as an alternative</tip>
<bascode>
<paragraph role="bascode" id="bas_id871666620966333" localize="false">Sub SF_Trace</paragraph>
<paragraph role="bascode" id="bas_id361666620966645" localize="false"> GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")</paragraph>
<paragraph role="bascode" id="bas_id391666620966798" localize="false"> svc = CreateScriptService("ScriptForge.Exception")</paragraph>
<paragraph role="bascode" id="bas_id821666620967245" localize="false"> svc.Console modal:=False</paragraph>
<paragraph role="bascode" id="bas_id741666621069519" localize="false"> svc.DebugPrint("Lorem", "Ipsum", "...")</paragraph>
<paragraph role="bascode" id="bas_id771666620967685" localize="false">End Sub ' SF_Trace</paragraph>
<paragraph role="bascode" id="bas_id451666683735574" localize="false"></paragraph>
<paragraph role="bascode" id="bas_id261666683736832" localize="false">Sub A2B_Trace</paragraph>
<paragraph role="bascode" id="bas_id61666683737033" localize="false"> GlobalScope.BasicLibraries.LoadLibrary("Access2Base")</paragraph>
<paragraph role="bascode" id="bas_id301666683737232" localize="false"> Access2Base.Trace.DebugPrint("Lorem", "Ipsum", "...")</paragraph>
<paragraph role="bascode" id="bas_id561666683737419" localize="false"> Access2Base.Trace.TraceConsole()</paragraph>
<paragraph role="bascode" id="bas_id251666683738645" localize="false">End Sub ' A2B_Trace</paragraph>
</bascode>
<section id="relatedtopics" >
<embed href="text/sbasic/python/python_listener.xhp#pythonlistener"/>
<paragraph role="paragraph" id="N0506"><link href="text/swriter/01/05060700.xhp">Events mapping to objects</link></paragraph>
<paragraph role="paragraph" id="N0509">See also <link href="text/sbasic/shared/01040000.xhp">Document events</link>, <link href="text/shared/02/01170202.xhp">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>
|
