From b122dcc35b2015c8ffd0f826dd99edfeeebb39d1 Mon Sep 17 00:00:00 2001 From: Alain Romedenne Date: Fri, 21 Oct 2022 10:23:30 +0200 Subject: [PATCH] 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 --- source/text/sbasic/python/python_listener.xhp | 3 +- source/text/sbasic/shared/03132000.xhp | 163 +++++++++++------- 2 files changed, 105 insertions(+), 61 deletions(-) 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 @@ Listeners are usually coded along with dialog opening. Numerous listener approaches are possible such as event handlers for dialogs or event monitors for documents or forms.
- CreateUnoListener Function + + Events mapping to objects See also Document events, Form events. 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 @@ -
CreateUnoListener function - -CreateUnoListener Function +

CreateUnoListener Function

Creates a Listener instance.
-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. +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 CreateUnoListener function sets a listener interface associated to an UNO object. The listener interface is then bound to its associated object. + -oListener = CreateUnoListener( Prefixname, ListenerInterfaceName ) - -The following example is based on a Basic library object. -Dim oListener + CreateUnoListener( Prefix As String, Typename As String) As Object + + +Prefix: A text prefix used in BASIC subroutines that handle events. +Typename: A fully qualified UNO listener interface name. + +The UNO service corresponding to the Typename listener interface name, Null value otherwise. + +The following example listens to events occuring for a BASIC library object. + +Dim oListener As Object oListener = CreateUnoListener( "ContListener_","com.sun.star.container.XContainerListener" ) -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. -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: +The CreateUnoListener method requires two parameters. The first is Prefix and is explained in detail below. Typename second parameter is the fully qualified name of the listener interface. +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 'addFooListener', where 'Foo' is the object type of the listener interface, without the 'X'. In this example, the addContainerListener method is called to register the XContainerListener: -Dim oLib +Dim oLib As Object oLib = BasicLibraries.Library1 ' Library1 must exist! oLib.addContainerListener( oListener ) ' Register the listener -The Listener is now registered. When an event occurs, the corresponding Listener calls the appropriate method from the com.sun.star.container.XContainerListener Interface. -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. -In this example, the Listener-Interface uses the following methods: +The listener is now registered. When an event occurs, the active listener calls the appropriate method defined in com.sun.star.container.XContainerListener interface. + + Event-driven registered BASIC subroutines require to use a defined Prefix. 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. +In this example, com.sun.star.container.XContainerListener interface defines the following methods: + + + + method + + + description + + + + + disposing + + + com.sun.star.lang.XEventListener base interface for all Listener Interfaces + + + + + elementInserted + + + Method of the com.sun.star.container.XContainerListener interface + + + + + elementRemoved + + + Method of the com.sun.star.container.XContainerListener interface + + + + + elementReplaced + + + Method of the com.sun.star.container.XContainerListener interface + + +
+ +'ContListener_' used in this example implies that the following subroutines must be implemented in BASIC: - disposing: + ContListener_disposing - Listener base interface (com.sun.star.lang.XEventListener): base interface for all Listener Interfaces + ContListener_elementInserted - elementInserted: + ContListener_elementRemoved - Method of the com.sun.star.container.XContainerListener interface - - - elementRemoved: - - - Method of the com.sun.star.container.XContainerListener interface - - - elementReplaced: - - - Method of the com.sun.star.container.XContainerListener interface + ContListener_elementReplaced -In this example, the prefix is ContListener_. The following subroutines must therefore be implemented in Basic: - - - - ContListener_disposing - - - ContListener_elementInserted - - - ContListener_elementRemoved - - - ContListener_elementReplaced - -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: +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 Sub declaration. For example: -Sub ContListener_disposing( oEvent ) +Sub ContListener_disposing( oEvent As com.sun.star.lang.EventObject ) MsgBox "disposing" - MsgBox oEvent.Dbg_Properties End Sub -Sub ContListener_elementInserted( oEvent ) - MsgBox "elementInserted" - MsgBox oEvent.Dbg_Properties +Sub ContListener_elementInserted( oEvent As com.sun.star.container.ContainerEvent ) + MsgBox oEvent.Source.' "elementInserted" End Sub -Sub ContListener_elementRemoved( oEvent ) +Sub ContListener_elementRemoved( oEvent As com.sun.star.container.ContainerEvent ) MsgBox "elementRemoved" - MsgBox oEvent.Dbg_Properties End Sub -Sub ContListener_elementReplaced( oEvent ) +Sub ContListener_elementReplaced( oEvent As com.sun.star.container.ContainerEvent ) MsgBox "elementReplaced" - MsgBox oEvent.Dbg_Properties End Sub -You do not need to include the parameter of an event object if the object is not used: +Not need to include the event object parameter when not used: ' Minimal implementation of Sub disposing -Sub ContListener_disposing -End Sub +Sub ContListener_disposing +End Sub + +Listener methods must always be implemented to avoid BASIC run-time errors. +Use ScriptForge library console when the BASIC IDE is not easily accessible, that is during events processing. Use the DebugPrint 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 Trace module of Access2Base library as an alternative + + Sub SF_Trace + GlobalScope.BasicLibraries.LoadLibrary("ScriptForge") + svc = CreateScriptService("ScriptForge.Exception") + svc.Console modal:=False + svc.DebugPrint("Lorem", "Ipsum", "...") + End Sub ' SF_Trace + + Sub A2B_Trace + GlobalScope.BasicLibraries.LoadLibrary("Access2Base") + Access2Base.Trace.DebugPrint("Lorem", "Ipsum", "...") + Access2Base.Trace.TraceConsole() + End Sub ' A2B_Trace -Listener methods must always be implemented to avoid Basic run-time errors. - +
+ + Events mapping to objects + See also Document events, Form events. + + +
+ +