Difference between revisions of "Documentation/DevGuide/ProUNO/Basic/Listeners"

Revision as of 20:20, 14 July 2018

Many interfaces in UNO are used to register listener objects implementing special listener interfaces, so that a listener gets feedback when its appropriate listener methods are called. OpenOffice.org Basic does not support the concept of object implementation, therefore a special RTL function named CreateUnoListener() has been introduced. It uses a prefix for method names that can be called back from UNO. The CreateUnoListener() expects a method name prefix and the type name of the desired listener interface. It returns an object that supports this interface that can be used to register the listener.

The following example instantiates an com.sun.star.container.XContainerListener. Note the prefix ContListener_:

  Dim oListener
  oListener = CreateUnoListener( "ContListener_", "com.sun.star.container.XContainerListener" )

The next step is to implement the listener methods. In this example, the listener interface has the following methods:

In the example, ContListener_ is specified as a name prefix, therefore the following subs have to be implemented in Basic.

• ContListener_disposing
• ContListener_elementInserted
• ContListener_elementRemoved
• ContListener_elementReplaced

Every listener type has a corresponding Event struct type that contains information about the event. When a listener method is called, an instance of this Event type is passed as a parameter. In the Basic listener methods these Event objects can be evaluated by adding an appropriate Variant parameter to the procedure header. The following code shows how the listener methods in the example could be implemented:

  Sub ContListener_disposing( oEvent )
      MsgBox "disposing"
      MsgBox oEvent.Dbg_Properties
  End Sub
 
  Sub ContListener_elementInserted( oEvent )
      MsgBox "elementInserted"
      MsgBox oEvent.Dbg_Properties
  End Sub
 
  Sub ContListener_elementRemoved( oEvent )
      MsgBox "elementRemoved"
      MsgBox oEvent.Dbg_Properties
  End Sub
 
  Sub ContListener_elementReplaced( oEvent )
      MsgBox "elementReplaced"
      MsgBox oEvent.Dbg_Properties
  End Sub

It is necessary to implement all listener methods, including the listener methods of the parent interfaces of a listener. Basic runtime errors will occur whenever an event occurs and no corresponding Basic sub is found, especially with disposing(), because the broadcaster might be destroyed a long time after the Basic program was ran. In this situation, Basic shows a "Method not found" message. There is no indication of which method cannot be found or why Basic is looking for a method.

We are listening for events at the basic library container. Our simple implementation for events triggered by user actions in the Tools - Macro - Organizer dialog displays a message box with the corresponding listener method name and a message box with the Dbg_Properties of the event struct. For the disposing() method, the type of the event object is com.sun.star.lang.EventObject. All other methods belong to com.sun.star.container.XContainerListener, therefore the type of the event object is com.sun.star.container.ContainerEvent. This type is derived from com.sun.star.lang.EventObject and contains additional container related information.

If the event object is not needed, the parameter could be left out of the implementation. For example, the disposing() method could be:

  ' Minimal implementation of Sub disposing
  Sub ContListener_disposing
  End Sub

The event objects passed to the listener methods can be accessed like other struct objects. The following code shows an enhanced implementation of the elementRemoved() method that evaluates the com.sun.star.container.ContainerEvent to display the name of the module removed from Library1 and the module source code:

  sub ContListener_ElementRemoved( oEvent )
      MsgBox "Element " + oEvent.Accessor + " removed"
      MsgBox "Source =" + Chr$(13) + Chr$(13) + oEvent.Element
  End Sub

When the user removes Module1, the following message boxes are displayed by ContListener_ElementRemoved():

ContListener_ElementRemoved message

ContListener_ElementRemoved Event Callback

When all necessary listener methods are implemented, add the listener to the broadcaster object by calling the appropriate add method. To register an XContainerListener, the corresponding registration method at our container is addContainerListener():

  Dim oLib
  oLib = BasicLibraries.Library1         ' Library1 must exist!
  oLib.addContainerListener( oListener ) ' Register the listener

The naming scheme XSomeEventListener <> addSomeEventListener() is used throughout the OpenOffice.org API.

The listener for container events is now registered permanently. When a container event occurs, the container calls the appropriate method of the com.sun.star.container.XContainerListener interface in our Basic code.