Contents

# CreateUnoListener Function

Creates a Listener instance.

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.

### Syntax:

        CreateUnoListener( Prefix As String, Typename As String) As Object

### Parameters:

Name | Type | Description
--- | --- | ---
Prefix | String | A text prefix used in BASIC subroutines that handle events.
Typename | String | A fully qualified UNO listener interface name.

### Return type:

Object. The UNO service corresponding to the Typename listener interface name, Null value otherwise.

### Example:

The following example listens to events occurring 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 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 LibreOfficeDev 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 As Object
    oLib = BasicLibraries.Library1 ' Library1 must exist!
    oLib.addContainerListener( oListener ) ' Register the listener

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:

- ContListener_disposing

- ContListener_elementInserted

- ContListener_elementRemoved

- ContListener_elementReplaced

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 As com.sun.star.lang.EventObject )
        MsgBox "disposing"
    End Sub

    Sub ContListener_elementInserted( oEvent As com.sun.star.container.ContainerEvent )
        MsgBox oEvent.Source.' "elementInserted"
    End Sub

    Sub ContListener_elementRemoved( oEvent As com.sun.star.container.ContainerEvent )
        MsgBox "elementRemoved"
    End Sub

    Sub ContListener_elementReplaced( oEvent As com.sun.star.container.ContainerEvent )
        MsgBox "elementReplaced"
    End Sub

Not need to include the event object parameter when not used:

    ' Minimal implementation of Sub disposing
    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

Related Topics

Creating Event Listeners

Events mapping to objects

See also Document events, Form events.

Creating a Dialog Handler

Listening to Document Events

UNO Objects, Functions and Services