LCOV - code coverage report
Current view: top level - include/comphelper - listenernotification.hxx (source / functions) Hit Total Coverage
Test: commit 10e77ab3ff6f4314137acd6e2702a6e5c1ce1fae Lines: 12 39 30.8 %
Date: 2014-11-03 Functions: 8 44 18.2 %
Legend: Lines: hit not hit

          Line data    Source code
       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 <cppuhelper/interfacecontainer.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             : 
      36             :     //= OListenerContainer
      37             : 
      38             :     /** abstract base class which manages a listener container, including
      39             :         THB's listener notification pattern which cares for removing listeners
      40             :         which throw an DisposedException upon notification
      41             : 
      42             :         Using this class is pretty easy:
      43             :         <ul>
      44             :             <li>Derive from it, and overwrite implNotify.</li>
      45             :             <li>Use <member>impl_addListener</member> and <member>impl_removeListener</member> in your
      46             :                 XFoo::addFooListener and XFoo::removeFooListener methods.</li>
      47             :             <li>call <member>impl_notify</member> whenever the event you want to notify happened</li>
      48             :             <li>call <member>disposing</member> upon the disposal of your broadcaster.</li>
      49             :         </ul>
      50             : 
      51             :         See OListenerContainerBase for an implementation which even saves
      52             :         you some more work, by doing the casts for you.
      53             : 
      54             :         @see http://www.openoffice.org/servlets/ReadMsg?list=interface-announce&msgId=494345
      55             :         @see OListenerContainerBase
      56             :     */
      57             :     class COMPHELPER_DLLPUBLIC OListenerContainer
      58             :     {
      59             :     private:
      60             :         ::cppu::OInterfaceContainerHelper    m_aListeners;
      61             : 
      62             :     public:
      63             :         /** sends a XEventObject::disposing notification to all listeners, and clears the
      64             :             listener container
      65             : 
      66             :             You'll usually call this from within your own dispose/disposing method
      67             :         */
      68             :         void    disposing( const ::com::sun::star::lang::EventObject& _rEventSource );
      69             : 
      70             :         /** clears the container without calling <member scope="com::sun::star::lang">XEventListener::disposing</member>
      71             :             at the listeners
      72             :         */
      73             :         void    clear();
      74             : 
      75             :         /** determines whether the listener container is currently empty
      76             :         */
      77             :         inline bool
      78             :                 empty() const;
      79             : 
      80             :         /** determines the number of elements in the container
      81             :         */
      82             :         inline size_t
      83             :                 size() const;
      84             : 
      85             :         /** creates an iterator for looping through all registered listeners
      86             :         */
      87           0 :         ::std::unique_ptr< ::cppu::OInterfaceIteratorHelper > createIterator()
      88             :         {
      89           0 :             ::std::unique_ptr< ::cppu::OInterfaceIteratorHelper > pIterator( new ::cppu::OInterfaceIteratorHelper( m_aListeners ) );
      90           0 :             return pIterator;
      91             :         }
      92             : 
      93             :     protected:
      94             :                 OListenerContainer( ::osl::Mutex& _rMutex );
      95             : 
      96             :         virtual ~OListenerContainer();
      97             : 
      98             :         void    impl_addListener( const ::com::sun::star::uno::Reference< ::com::sun::star::lang::XEventListener >& _rxListener );
      99             :         void    impl_removeListener( const ::com::sun::star::uno::Reference< ::com::sun::star::lang::XEventListener >& _rxListener );
     100             : 
     101             :         /** notifies all listeners of the given event, using THB's notification pattern
     102             : 
     103             :             internally, this method will call <member>implNotify</member> for every listener
     104             : 
     105             :             @return
     106             :                 <TRUE/> if all listeners have been notified, <FALSE/> else. The latter can happen
     107             :                 if <member>implNotify</member> cancelles the notification loop.
     108             : 
     109             :             @see implNotify
     110             :         */
     111             :         bool    impl_notify( const ::com::sun::star::lang::EventObject& _rEvent );
     112             : 
     113             :     protected:
     114             :         /** call a single listener
     115             : 
     116             :             @pure
     117             : 
     118             :             @throws ::com::sun::star::uno::Exception
     119             :                 if the listener throws an exception during notification. Please don't catch
     120             :                 any listener exceptions in your implementation of this method, simply let them
     121             :                 pass to the caller.
     122             : 
     123             :             @param _rxListener
     124             :                 specifies the listener to call. Is guaranteed to not be <NULL/>
     125             :             @param _rEvent
     126             :                 the event to broadcast. This is the same as passed to <member>notify</member>, so if
     127             :                 your base class knows the type passed into <member>notify</member>, it can safely assume
     128             :                 that <arg>_rEvent</arg> is also of this type.
     129             : 
     130             :             @return
     131             :                 <TRUE/> if the remaining listeners should be called, <FALSE/> if the notification
     132             :                 loop should be cancelled
     133             : 
     134             :             @see notify
     135             :         */
     136             :         virtual bool    implNotify(
     137             :                             const ::com::sun::star::uno::Reference< ::com::sun::star::lang::XEventListener >& _rxListener,
     138             :                             const ::com::sun::star::lang::EventObject& _rEvent
     139             :                         ) = 0;
     140             :     };
     141             : 
     142             : 
     143           0 :     inline bool OListenerContainer::empty() const
     144             :     {
     145           0 :         return ( m_aListeners.getLength() == 0 );
     146             :     }
     147             : 
     148             :     inline size_t OListenerContainer::size() const
     149             :     {
     150             :         return m_aListeners.getLength();
     151             :     }
     152             : 
     153             : 
     154             :     //= OSimpleListenerContainer
     155             : 
     156             :     /** helper class for simple notification of the form LISTENER::METHOD( EVENT )
     157             : 
     158             :         This class is not threadsafe!
     159             : 
     160             :         @param LISTENER
     161             :             the listener class to call, e.g. com::sun::star::lang::XEventListener
     162             :         @param EVENT
     163             :             the event type to notify, e.g. com::sun::star::lang::EventObject
     164             :     */
     165             :     template< class LISTENER, class EVENT >
     166           2 :     class OSimpleListenerContainer : protected OListenerContainer
     167             :     {
     168             :     public:
     169             :         typedef LISTENER    ListenerClass;
     170             :         typedef EVENT       EventClass;
     171             :         typedef void ( SAL_CALL LISTENER::*NotificationMethod )( const EventClass& );
     172             : 
     173             :     private:
     174             :         NotificationMethod  m_pNotificationMethod;
     175             : 
     176             :     public:
     177           2 :         OSimpleListenerContainer( ::osl::Mutex& _rMutex )
     178             :             :OListenerContainer( _rMutex )
     179           2 :             ,m_pNotificationMethod( NULL )
     180             :         {
     181           2 :         }
     182             : 
     183           0 :         inline void addListener( const ::com::sun::star::uno::Reference< ListenerClass >& _rxListener )
     184             :         {
     185           0 :             OListenerContainer::impl_addListener( _rxListener.get() );
     186           0 :         }
     187             : 
     188           0 :         inline void removeListener( const ::com::sun::star::uno::Reference< ListenerClass >& _rxListener )
     189             :         {
     190           0 :             OListenerContainer::impl_removeListener( _rxListener.get() );
     191           0 :         }
     192             : 
     193             :         // publish some otherwise hidden base functionality
     194             :         using OListenerContainer::disposing;
     195             :         using OListenerContainer::clear;
     196             :         using OListenerContainer::empty;
     197             :         using OListenerContainer::size;
     198             :         using OListenerContainer::createIterator;
     199             : 
     200             :         /// typed notification
     201             :         inline bool    notify( const EventClass& _rEvent, NotificationMethod _pNotify );
     202             : 
     203             :     protected:
     204           0 :         virtual bool    implNotify(
     205             :                             const ::com::sun::star::uno::Reference< ::com::sun::star::lang::XEventListener >& _rxListener,
     206             :                             const ::com::sun::star::lang::EventObject& _rEvent
     207             :                         ) SAL_OVERRIDE
     208             :         {
     209           0 :             const EventClass& rTypedEvent( static_cast< const EventClass& >( _rEvent ) );
     210           0 :             ListenerClass* pTypedListener( static_cast< ListenerClass* >( _rxListener.get() ) );
     211           0 :             (pTypedListener->*m_pNotificationMethod)( rTypedEvent );
     212           0 :             return true;
     213             :         }
     214             :     };
     215             : 
     216             : 
     217             :     template< class LISTENER, class EVENT >
     218           0 :     inline bool OSimpleListenerContainer< LISTENER, EVENT >::notify( const EventClass& _rEvent, NotificationMethod _pNotify )
     219             :     {
     220           0 :         m_pNotificationMethod = _pNotify;
     221           0 :         bool bRet = OListenerContainer::impl_notify( _rEvent );
     222           0 :         m_pNotificationMethod = NULL;
     223           0 :         return bRet;
     224             :     }
     225             : 
     226             :     //= OListenerContainerBase
     227             : 
     228             :     /** is a specialization of OListenerContainer which saves you some additional type casts,
     229             :         by making the required listener and event types template arguments.
     230             :     */
     231             :     template< class LISTENER, class EVENT >
     232       11001 :     class OListenerContainerBase : public OListenerContainer
     233             :     {
     234             :     public:
     235             :         typedef LISTENER    ListenerClass;
     236             :         typedef EVENT       EventClass;
     237             : 
     238             :     public:
     239       11212 :         inline OListenerContainerBase( ::osl::Mutex& _rMutex ) : OListenerContainer( _rMutex )
     240             :         {
     241       11212 :         }
     242             : 
     243           2 :         inline void addTypedListener( const ::com::sun::star::uno::Reference< ListenerClass >& _rxListener )
     244             :         {
     245           2 :             OListenerContainer::impl_addListener( _rxListener.get() );
     246           2 :         }
     247             : 
     248           0 :         inline void removeTypedListener( const ::com::sun::star::uno::Reference< ListenerClass >& _rxListener )
     249             :         {
     250           0 :             OListenerContainer::impl_removeListener( _rxListener.get() );
     251           0 :         }
     252             : 
     253         104 :         inline bool notify( const EventClass& _rEvent )
     254             :         {
     255         104 :             return OListenerContainer::impl_notify( _rEvent );
     256             :         }
     257             : 
     258             :         using OListenerContainer::impl_notify;
     259             : 
     260             :     protected:
     261           0 :         virtual bool    implNotify(
     262             :                             const ::com::sun::star::uno::Reference< ::com::sun::star::lang::XEventListener >& _rxListener,
     263             :                             const ::com::sun::star::lang::EventObject& _rEvent
     264             :                         ) SAL_OVERRIDE
     265             :         {
     266             :             return implTypedNotify(
     267           0 :                 ::com::sun::star::uno::Reference< ListenerClass >( static_cast< ListenerClass* >( _rxListener.get() ) ),
     268             :                 static_cast< const EventClass& >( _rEvent )
     269           0 :             );
     270             :         }
     271             : 
     272             :         virtual bool    implTypedNotify(
     273             :                             const ::com::sun::star::uno::Reference< ListenerClass >& _rxListener,
     274             :                             const EventClass& _rEvent
     275             :                         ) = 0;
     276             :     };
     277             : 
     278             : } // namespace comphelper
     279             : 
     280             : 
     281             : #endif // INCLUDED_COMPHELPER_LISTENERNOTIFICATION_HXX
     282             : 
     283             : /* vim:set shiftwidth=4 softtabstop=4 expandtab: */

Generated by: LCOV version 1.10