include/comphelper/listenernotification.hxx

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19
  20 #ifndef INCLUDED_COMPHELPER_LISTENERNOTIFICATION_HXX
  21 #define INCLUDED_COMPHELPER_LISTENERNOTIFICATION_HXX
  22
  23 #include <comphelper/interfacecontainer2.hxx>
  24
  25 #include <com/sun/star/lang/XEventListener.hpp>
  26 #include <comphelper/comphelperdllapi.h>
  27
  28 #include <memory>
  29
  30
  31 namespace comphelper
  32 {
  33
  34
  35     //= OListenerContainer
  36
  37     /** abstract base class which manages a listener container, including
  38         THB's listener notification pattern which cares for removing listeners
  39         which throw an DisposedException upon notification
  40
  41         Using this class is pretty easy:
  42         <ul>
  43             <li>Derive from it, and overwrite implNotify.</li>
  44             <li>Use <member>impl_addListener</member> and <member>impl_removeListener</member> in your
  45                 XFoo::addFooListener and XFoo::removeFooListener methods.</li>
  46             <li>call <member>impl_notify</member> whenever the event you want to notify happened</li>
  47             <li>call <member>disposing</member> upon the disposal of your broadcaster.</li>
  48         </ul>
  49
  50         See OListenerContainerBase for an implementation which even saves
  51         you some more work, by doing the casts for you.
  52
  53         @see http://www.openoffice.org/servlets/ReadMsg?list=interface-announce&msgId=494345
  54         @see OListenerContainerBase
  55     */
  56     class COMPHELPER_DLLPUBLIC OListenerContainer
  57     {
  58     private:
  59         ::comphelper::OInterfaceContainerHelper2    m_aListeners;
  60
  61     public:
  62         /** sends a XEventObject::disposing notification to all listeners, and clears the
  63             listener container
  64
  65             You'll usually call this from within your own dispose/disposing method
  66         */
  67         void    disposing( const css::lang::EventObject& _rEventSource );
  68
  69         /** clears the container without calling <member scope="css::lang">XEventListener::disposing</member>
  70             at the listeners
  71         */
  72         void    clear();
  73
  74         /** determines whether the listener container is currently empty
  75         */
  76         inline bool
  77                 empty() const;
  78
  79         /** creates an iterator for looping through all registered listeners
  80         */
  81         ::std::unique_ptr< ::comphelper::OInterfaceIteratorHelper2 > createIterator()
  82         {
  83             ::std::unique_ptr< ::comphelper::OInterfaceIteratorHelper2 > pIterator( new ::comphelper::OInterfaceIteratorHelper2( m_aListeners ) );
  84             return pIterator;
  85         }
  86
  87     protected:
  88                 OListenerContainer( ::osl::Mutex& _rMutex );
  89
  90         virtual ~OListenerContainer();
  91
  92         void    impl_addListener( const css::uno::Reference< css::lang::XEventListener >& _rxListener );
  93         void    impl_removeListener( const css::uno::Reference< css::lang::XEventListener >& _rxListener );
  94
  95         /** notifies all listeners of the given event, using THB's notification pattern
  96
  97             internally, this method will call <member>implNotify</member> for every listener
  98
  99             @return
 100                 <TRUE/> if all listeners have been notified, <FALSE/> else. The latter can happen
 101                 if <member>implNotify</member> cancelles the notification loop.
 102
 103             @see implNotify
 104         */
 105         bool    impl_notify( const css::lang::EventObject& _rEvent );
 106
 107     protected:
 108         /** call a single listener
 109
 110             @pure
 111
 112             @throws css::uno::Exception
 113                 if the listener throws an exception during notification. Please don't catch
 114                 any listener exceptions in your implementation of this method, simply let them
 115                 pass to the caller.
 116
 117             @param _rxListener
 118                 specifies the listener to call. Is guaranteed to not be <NULL/>
 119             @param _rEvent
 120                 the event to broadcast. This is the same as passed to <member>notify</member>, so if
 121                 your base class knows the type passed into <member>notify</member>, it can safely assume
 122                 that <arg>_rEvent</arg> is also of this type.
 123
 124             @return
 125                 <TRUE/> if the remaining listeners should be called, <FALSE/> if the notification
 126                 loop should be cancelled
 127
 128             @see notify
 129         */
 130         virtual bool    implNotify(
 131                             const css::uno::Reference< css::lang::XEventListener >& _rxListener,
 132                             const css::lang::EventObject& _rEvent
 133                         ) = 0;
 134     };
 135
 136
 137     inline bool OListenerContainer::empty() const
 138     {
 139         return ( m_aListeners.getLength() == 0 );
 140     }
 141
 142
 143     //= OSimpleListenerContainer
 144
 145     /** helper class for simple notification of the form LISTENER::METHOD( EVENT )
 146
 147         This class is not threadsafe!
 148
 149         @param LISTENER
 150             the listener class to call, e.g. css::lang::XEventListener
 151         @param EVENT
 152             the event type to notify, e.g. css::lang::EventObject
 153     */
 154     template< class LISTENER, class EVENT >
 155     class OSimpleListenerContainer : protected OListenerContainer
 156     {
 157     public:
 158         typedef LISTENER    ListenerClass;
 159         typedef EVENT       EventClass;
 160         typedef void ( SAL_CALL LISTENER::*NotificationMethod )( const EventClass& );
 161
 162     private:
 163         NotificationMethod  m_pNotificationMethod;
 164
 165     public:
 166         OSimpleListenerContainer( ::osl::Mutex& _rMutex )
 167             :OListenerContainer( _rMutex )
 168             ,m_pNotificationMethod( nullptr )
 169         {
 170         }
 171
 172         inline void addListener( const css::uno::Reference< ListenerClass >& _rxListener )
 173         {
 174             OListenerContainer::impl_addListener( _rxListener.get() );
 175         }
 176
 177         inline void removeListener( const css::uno::Reference< ListenerClass >& _rxListener )
 178         {
 179             OListenerContainer::impl_removeListener( _rxListener.get() );
 180         }
 181
 182         // publish some otherwise hidden base functionality
 183         using OListenerContainer::disposing;
 184         using OListenerContainer::clear;
 185         using OListenerContainer::empty;
 186         using OListenerContainer::createIterator;
 187
 188         /// typed notification
 189         inline bool    notify( const EventClass& _rEvent, NotificationMethod _pNotify );
 190
 191     protected:
 192         virtual bool    implNotify(
 193                             const css::uno::Reference< css::lang::XEventListener >& _rxListener,
 194                             const css::lang::EventObject& _rEvent
 195                         ) override
 196         {
 197             const EventClass& rTypedEvent( static_cast< const EventClass& >( _rEvent ) );
 198             ListenerClass* pTypedListener( static_cast< ListenerClass* >( _rxListener.get() ) );
 199             (pTypedListener->*m_pNotificationMethod)( rTypedEvent );
 200             return true;
 201         }
 202     };
 203
 204
 205     template< class LISTENER, class EVENT >
 206     inline bool OSimpleListenerContainer< LISTENER, EVENT >::notify( const EventClass& _rEvent, NotificationMethod _pNotify )
 207     {
 208         m_pNotificationMethod = _pNotify;
 209         bool bRet = OListenerContainer::impl_notify( _rEvent );
 210         m_pNotificationMethod = nullptr;
 211         return bRet;
 212     }
 213
 214     //= OListenerContainerBase
 215
 216     /** is a specialization of OListenerContainer which saves you some additional type casts,
 217         by making the required listener and event types template arguments.
 218     */
 219     template< class LISTENER, class EVENT >
 220     class OListenerContainerBase : public OListenerContainer
 221     {
 222     public:
 223         typedef LISTENER    ListenerClass;
 224         typedef EVENT       EventClass;
 225
 226     public:
 227         inline OListenerContainerBase( ::osl::Mutex& _rMutex ) : OListenerContainer( _rMutex )
 228         {
 229         }
 230
 231         inline void addTypedListener( const css::uno::Reference< ListenerClass >& _rxListener )
 232         {
 233             OListenerContainer::impl_addListener( _rxListener.get() );
 234         }
 235
 236         inline void removeTypedListener( const css::uno::Reference< ListenerClass >& _rxListener )
 237         {
 238             OListenerContainer::impl_removeListener( _rxListener.get() );
 239         }
 240
 241         inline bool notify( const EventClass& _rEvent )
 242         {
 243             return OListenerContainer::impl_notify( _rEvent );
 244         }
 245
 246         using OListenerContainer::impl_notify;
 247
 248     protected:
 249         virtual bool    implNotify(
 250                             const css::uno::Reference< css::lang::XEventListener >& _rxListener,
 251                             const css::lang::EventObject& _rEvent
 252                         ) override
 253         {
 254             return implTypedNotify(
 255                 css::uno::Reference< ListenerClass >( static_cast< ListenerClass* >( _rxListener.get() ) ),
 256                 static_cast< const EventClass& >( _rEvent )
 257             );
 258         }
 259
 260         virtual bool    implTypedNotify(
 261                             const css::uno::Reference< ListenerClass >& _rxListener,
 262                             const EventClass& _rEvent
 263                         ) = 0;
 264     };
 265
 266 } // namespace comphelper
 267
 268
 269 #endif // INCLUDED_COMPHELPER_LISTENERNOTIFICATION_HXX
 270
 271 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */