1 /************************************************************** 2 * 3 * Licensed to the Apache Software Foundation (ASF) under one 4 * or more contributor license agreements. See the NOTICE file 5 * distributed with this work for additional information 6 * regarding copyright ownership. The ASF licenses this file 7 * to you under the Apache License, Version 2.0 (the 8 * "License"); you may not use this file except in compliance 9 * with the License. You may obtain a copy of the License at 10 * 11 * http://www.apache.org/licenses/LICENSE-2.0 12 * 13 * Unless required by applicable law or agreed to in writing, 14 * software distributed under the License is distributed on an 15 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 16 * KIND, either express or implied. See the License for the 17 * specific language governing permissions and limitations 18 * under the License. 19 * 20 *************************************************************/ 21 22 23 24 #ifndef COMPHELPER_ACCESSIBLE_EVENT_NOTIFIER 25 #define COMPHELPER_ACCESSIBLE_EVENT_NOTIFIER 26 27 #include <com/sun/star/accessibility/AccessibleEventObject.hpp> 28 #include <com/sun/star/accessibility/XAccessibleEventListener.hpp> 29 #include <osl/thread.hxx> 30 #include <osl/conditn.hxx> 31 #include <cppuhelper/interfacecontainer.h> 32 #include "comphelper/comphelperdllapi.h" 33 34 #include <map> 35 #include <list> 36 37 //......................................................................... 38 namespace comphelper 39 { 40 //......................................................................... 41 42 //===================================================================== 43 //= AccessibleEventNotifier 44 //===================================================================== 45 class COMPHELPER_DLLPUBLIC AccessibleEventNotifier 46 { 47 // typedefs 48 public: 49 typedef sal_uInt32 TClientId; 50 51 typedef ::std::pair< TClientId, ::com::sun::star::accessibility::AccessibleEventObject > 52 ClientEvent; 53 54 typedef ::cppu::OInterfaceContainerHelper EventListeners; 55 typedef ::std::map< TClientId, EventListeners*, ::std::less< TClientId > > ClientMap; 56 57 protected: 58 AccessibleEventNotifier( ); // never implemented 59 ~AccessibleEventNotifier( ); // never implemented 60 61 private: 62 COMPHELPER_DLLPRIVATE AccessibleEventNotifier( const AccessibleEventNotifier& ); // never implemented! 63 COMPHELPER_DLLPRIVATE AccessibleEventNotifier& operator=( const AccessibleEventNotifier& ); // never implemented! 64 65 public: 66 /** registers a client of this class, means a broadcaster of AccessibleEvents 67 68 <p>No precaution is taken to care for disposal of this component. When the component 69 dies, it <b>must</b> call <member>revokeClient</member> or <member>revokeClientNotifyDisposing</member> 70 explicitly itself.</p> 71 */ 72 static TClientId registerClient( ); 73 74 /** revokes a broadcaster of AccessibleEvents 75 76 <p>Note that no disposing event is fired when you use this method, the client is simply revoked. 77 You can for instance revoke a client if the last listener for it is revoked, but the client 78 itself is not disposed.<br/> 79 When the client is disposed, you should prefer <member>revokeClientNotifyDisposing</member></p> 80 81 <p>Any possibly pending events for this client are removed from the queue.</p> 82 83 @seealso revokeClientNotifyDisposing 84 */ 85 static void revokeClient( const TClientId _nClient ); 86 87 /** revokes a client, with additionally notifying a disposing event to all listeners registered for 88 this client 89 90 <p>Any other possibly pending events for this client are removed from the queue</p> 91 92 @param _nClient 93 the id of the client which should be revoked 94 @param _rxEventSource 95 the source to be notified together with the <member scope="com.sun.star.lang">XComponent::disposing</member> 96 call. 97 */ 98 static void revokeClientNotifyDisposing( 99 const TClientId _nClient, 100 const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >& _rxEventSource 101 ) SAL_THROW( ( ) ); 102 103 /** registers a listener for the given client 104 105 @param _nClient 106 the id of the client for which a listener should be registered 107 @return 108 the number of event listeners currently registered for this client 109 */ 110 static sal_Int32 addEventListener( 111 const TClientId _nClient, 112 const ::com::sun::star::uno::Reference< ::com::sun::star::accessibility::XAccessibleEventListener >& _rxListener 113 ) SAL_THROW( ( ) ); 114 115 /** revokes a listener for the given client 116 117 @param _nClient 118 the id of the client for which a listener should be revoked 119 @return 120 the number of event listeners currently registered for this client 121 */ 122 static sal_Int32 removeEventListener( 123 const TClientId _nClient, 124 const ::com::sun::star::uno::Reference< ::com::sun::star::accessibility::XAccessibleEventListener >& _rxListener 125 ) SAL_THROW( ( ) ); 126 127 /** retrieves the set of listeners registered for a given client 128 */ 129 static ::com::sun::star::uno::Sequence< ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface > > 130 getEventListeners( const TClientId _nClient ) SAL_THROW( ( ) ); 131 132 /** adds an event, which is to be braodcasted, to the queue 133 134 @param _nClient 135 the id of the client which needs to broadcast the event 136 */ 137 static void addEvent( 138 const TClientId _nClient, 139 const ::com::sun::star::accessibility::AccessibleEventObject& _rEvent 140 ) SAL_THROW( ( ) ); 141 142 private: 143 /// generates a new client id 144 COMPHELPER_DLLPRIVATE static TClientId generateId(); 145 146 /** looks up a client in our client map, asserts if it cannot find it or no event thread is present 147 148 @precond 149 to be called with our mutex locked 150 151 @param _nClient 152 the id of the client to loopup 153 @param _rPos 154 out-parameter for the position of the client in the client map 155 156 @return 157 <TRUE/> if and only if the client could be found and <arg>_rPos</arg> has been filled with 158 it's position 159 */ 160 COMPHELPER_DLLPRIVATE static sal_Bool implLookupClient( const TClientId _nClient, ClientMap::iterator& _rPos ); 161 }; 162 163 //......................................................................... 164 } // namespace comphelper 165 //......................................................................... 166 167 #endif // COMPHELPER_ACCESSIBLE_EVENT_NOTIFIER 168 169 170