Listeners

OpenOffice.org Developer's Guide

Professional UNO

< Previous Section

Next Section >

• Introduction
• API Concepts

• Data Types

• Simple Types
• The Any Type
• Interfaces
• Services
• Structs
• Predefined Values
• Sequences
• Modules
• Exceptions
• Singletons

• Understanding the API Reference

• UNO Concepts

• UNO Interprocess Connections

• Starting OpenOffice.org in Listening Mode
• Importing a UNO Object
• Characteristics of the Interprocess Bridge
• Opening a Connection
• Creating the Bridge
• Closing a Connection
• Example: A Connection Aware Client

• Service Manager and Component Context

• Service Manager
• Component Context

• Using UNO Interfaces
• Properties
• Collections and Containers
• Event Model
• Exception Handling
• Lifetime of UNO objects

• acquire() and release()
• The XComponent Interface
• Children of the XEventListener Interface
• Weak Objects and References
• Differences Between the Lifetime of C++ and Java Objects

• Object Identity

• UNO Language Bindings

• Java Language Binding

• Getting a Service Manager
• Transparent Use of Office UNO Components
• Handling Interfaces
• Type Mappings

• Mapping of Sequence Types
• Mapping of Enum Types
• Mapping of Struct Types
• Mapping of Exception Types
• Mapping of Interface Types
• Mapping of UNOIDL
• Mapping of Services
• Mapping of Singletons
• Inexact approximation of UNO Value Semantics

• C++ Language Binding

• Establishing Interprocess Connections
• Transparent Use of Office UNO Components
• Type Mappings

• Mapping of Struct Types
• Mapping of Interface Types
• Mapping of Sequence Types
• Mapping of Services
• Mapping of Singletons

• Using Weak References
• Exception Handling in C++

• OpenOffice.org Basic

• Handling UNO Objects

• Instantiating UNO Services
• Getting Information about UNO Objects

• Mapping of UNO and Basic Types

• Mapping of Simple Types
• Mapping of Sequences and Arrays
• Mapping of Structs
• Mapping of Enums and Constant Groups

• Case Sensitivity
• Exception Handling
• Listeners

• Automation Bridge

• The Service Manager Component
• Using UNO from Automation

• Calling Functions and Accessing Properties
• Return Values
• Usage of Types

• Using Automation Objects from UNO
• Type Mappings

• Default Mappings

• Mapping of Simple Types
• Mapping of Hyper and Decimal
• Mapping of String
• Mapping of Interfaces and Structures
• Mapping of Sequence
• Mapping of Type

• Conversion Mappings
• Client-Side Conversions
• Value Objects
• Exceptions and Errorcodes

• Automation Objects with UNO Interfaces
• DCOM
• The Bridge Services
• Unsupported COM Features

• CLI Language Binding

• The Language Binding DLLs
• Type Mapping

• Type Name Decoration
• Type Mappings
• Additional Structures

• Lifetime Management and Obtaining Interfaces
• Writing Client Programs

• The Override Problem
• Important Interfaces and Implementations

< Previous Page

Next Page >

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. Apache OpenOffice 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:

Methods of com.sun.star.container.XContainerListener
disposing()	Method of the listener base interface com.sun.star.lang.XEventListener, contained in every listener interface, because all listener interfaces must be derived from this base interface. Takes a com.sun.star.lang.EventObject
elementInserted()	Method of interface com.sun.star.container.XContainerListener. Takes a com.sun.star.container.ContainerEvent.
elementRemoved()	Method of interface com.sun.star.container.XContainerListener. Takes a com.sun.star.container.ContainerEvent.
elementReplaced()	Method of interface com.sun.star.container.XContainerListener. Takes a com.sun.star.container.ContainerEvent.

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 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 Apache OpenOffice 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.

Content on this page is licensed under the Public Documentation License (PDL).