include/comphelper/accessibleeventnotifier.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 COMPHELPER_ACCESSIBLE_EVENT_NOTIFIER
  21 #define COMPHELPER_ACCESSIBLE_EVENT_NOTIFIER
  22
  23 #include <com/sun/star/accessibility/AccessibleEventObject.hpp>
  24 #include <com/sun/star/accessibility/XAccessibleEventListener.hpp>
  25 #include <osl/thread.hxx>
  26 #include <osl/conditn.hxx>
  27 #include <cppuhelper/interfacecontainer.h>
  28 #include "comphelper/comphelperdllapi.h"
  29
  30 #include <map>
  31 #include <list>
  32
  33 //.........................................................................
  34 namespace comphelper
  35 {
  36 //.........................................................................
  37
  38     //=====================================================================
  39     //= AccessibleEventNotifier
  40     //=====================================================================
  41     class COMPHELPER_DLLPUBLIC AccessibleEventNotifier
  42     {
  43     // typedefs
  44     public:
  45         typedef sal_uInt32  TClientId;
  46
  47         typedef ::std::pair< TClientId, ::com::sun::star::accessibility::AccessibleEventObject >
  48                                                                                     ClientEvent;
  49
  50         typedef ::cppu::OInterfaceContainerHelper                                   EventListeners;
  51         typedef ::std::map< TClientId, EventListeners*, ::std::less< TClientId > >  ClientMap;
  52
  53     protected:
  54         AccessibleEventNotifier( );     // never implemented
  55         ~AccessibleEventNotifier( );    // never implemented
  56
  57     private:
  58         COMPHELPER_DLLPRIVATE AccessibleEventNotifier( const AccessibleEventNotifier& );                // never implemented!
  59         COMPHELPER_DLLPRIVATE AccessibleEventNotifier& operator=( const AccessibleEventNotifier& ); // never implemented!
  60
  61     public:
  62         /** registers a client of this class, means a broadcaster of AccessibleEvents
  63
  64             <p>No precaution is taken to care for disposal of this component. When the component
  65             dies, it <b>must</b> call <member>revokeClient</member> or <member>revokeClientNotifyDisposing</member>
  66             explicitly itself.</p>
  67         */
  68         static  TClientId   registerClient( );
  69
  70         /** revokes a broadcaster of AccessibleEvents
  71
  72             <p>Note that no disposing event is fired when you use this method, the client is simply revoked.
  73             You can for instance revoke a client if the last listener for it is revoked, but the client
  74             itself is not disposed.<br/>
  75             When the client is disposed, you should prefer <member>revokeClientNotifyDisposing</member></p>
  76
  77             <p>Any possibly pending events for this client are removed from the queue.</p>
  78
  79             @seealso revokeClientNotifyDisposing
  80         */
  81         static  void        revokeClient( const TClientId _nClient );
  82
  83         /** revokes a client, with additionally notifying a disposing event to all listeners registered for
  84             this client
  85
  86             <p>Any other possibly pending events for this client are removed from the queue</p>
  87
  88             @param _nClient
  89                 the id of the client which should be revoked
  90             @param _rxEventSource
  91                 the source to be notified together with the <member scope="com.sun.star.lang">XComponent::disposing</member>
  92                 call.
  93         */
  94         static  void        revokeClientNotifyDisposing(
  95                         const TClientId _nClient,
  96                         const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >& _rxEventSource
  97                     ) SAL_THROW( ( ) );
  98
  99         /** registers a listener for the given client
 100
 101             @param _nClient
 102                 the id of the client for which a listener should be registered
 103             @return
 104                 the number of event listeners currently registered for this client
 105         */
 106         static sal_Int32 addEventListener(
 107                         const TClientId _nClient,
 108                         const ::com::sun::star::uno::Reference< ::com::sun::star::accessibility::XAccessibleEventListener >& _rxListener
 109                     ) SAL_THROW( ( ) );
 110
 111         /** revokes a listener for the given client
 112
 113             @param _nClient
 114                 the id of the client for which a listener should be revoked
 115             @return
 116                 the number of event listeners currently registered for this client
 117         */
 118         static sal_Int32 removeEventListener(
 119                         const TClientId _nClient,
 120                         const ::com::sun::star::uno::Reference< ::com::sun::star::accessibility::XAccessibleEventListener >& _rxListener
 121                     ) SAL_THROW( ( ) );
 122
 123         /** adds an event, which is to be braodcasted, to the queue
 124
 125             @param _nClient
 126                 the id of the client which needs to broadcast the event
 127         */
 128         static void addEvent(
 129                         const TClientId _nClient,
 130                         const ::com::sun::star::accessibility::AccessibleEventObject& _rEvent
 131                     ) SAL_THROW( ( ) );
 132
 133     private:
 134         /// generates a new client id
 135         COMPHELPER_DLLPRIVATE static    TClientId   generateId();
 136
 137         /** looks up a client in our client map, asserts if it cannot find it or no event thread is present
 138
 139             @precond
 140                 to be called with our mutex locked
 141
 142             @param _nClient
 143                 the id of the client to loopup
 144             @param _rPos
 145                 out-parameter for the position of the client in the client map
 146
 147             @return
 148                 <TRUE/> if and only if the client could be found and <arg>_rPos</arg> has been filled with
 149                 it's position
 150         */
 151         COMPHELPER_DLLPRIVATE static    sal_Bool    implLookupClient( const TClientId _nClient, ClientMap::iterator& _rPos );
 152     };
 153
 154 //.........................................................................
 155 }   // namespace comphelper
 156 //.........................................................................
 157
 158 #endif // COMPHELPER_ACCESSIBLE_EVENT_NOTIFIER
 159
 160
 161 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */