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
  26 #include <comphelper/comphelperdllapi.h>
  27
  28 //.........................................................................
  29 namespace comphelper
  30 {
  31 //.........................................................................
  32
  33     //=====================================================================
  34     //= AccessibleEventNotifier
  35     //=====================================================================
  36     class COMPHELPER_DLLPUBLIC AccessibleEventNotifier
  37     {
  38     // typedefs
  39     public:
  40         typedef sal_uInt32  TClientId;
  41
  42     protected:
  43         AccessibleEventNotifier( );     // never implemented
  44         ~AccessibleEventNotifier( );    // never implemented
  45
  46     private:
  47         COMPHELPER_DLLPRIVATE AccessibleEventNotifier( const AccessibleEventNotifier& );                // never implemented!
  48         COMPHELPER_DLLPRIVATE AccessibleEventNotifier& operator=( const AccessibleEventNotifier& ); // never implemented!
  49
  50     public:
  51         /** registers a client of this class, means a broadcaster of AccessibleEvents
  52
  53             <p>No precaution is taken to care for disposal of this component. When the component
  54             dies, it <b>must</b> call <member>revokeClient</member> or <member>revokeClientNotifyDisposing</member>
  55             explicitly itself.</p>
  56         */
  57         static  TClientId   registerClient( );
  58
  59         /** revokes a broadcaster of AccessibleEvents
  60
  61             <p>Note that no disposing event is fired when you use this method, the client is simply revoked.
  62             You can for instance revoke a client if the last listener for it is revoked, but the client
  63             itself is not disposed.<br/>
  64             When the client is disposed, you should prefer <member>revokeClientNotifyDisposing</member></p>
  65
  66             <p>Any possibly pending events for this client are removed from the queue.</p>
  67
  68             @seealso revokeClientNotifyDisposing
  69         */
  70         static  void        revokeClient( const TClientId _nClient );
  71
  72         /** revokes a client, with additionally notifying a disposing event to all listeners registered for
  73             this client
  74
  75             <p>Any other possibly pending events for this client are removed from the queue</p>
  76
  77             @param _nClient
  78                 the id of the client which should be revoked
  79             @param _rxEventSource
  80                 the source to be notified together with the <member scope="com.sun.star.lang">XComponent::disposing</member>
  81                 call.
  82         */
  83         static  void        revokeClientNotifyDisposing(
  84                         const TClientId _nClient,
  85                         const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >& _rxEventSource
  86                     ) SAL_THROW( ( ) );
  87
  88         /** registers a listener for the given client
  89
  90             @param _nClient
  91                 the id of the client for which a listener should be registered
  92             @return
  93                 the number of event listeners currently registered for this client
  94         */
  95         static sal_Int32 addEventListener(
  96                         const TClientId _nClient,
  97                         const ::com::sun::star::uno::Reference< ::com::sun::star::accessibility::XAccessibleEventListener >& _rxListener
  98                     ) SAL_THROW( ( ) );
  99
 100         /** revokes a listener for the given client
 101
 102             @param _nClient
 103                 the id of the client for which a listener should be revoked
 104             @return
 105                 the number of event listeners currently registered for this client
 106         */
 107         static sal_Int32 removeEventListener(
 108                         const TClientId _nClient,
 109                         const ::com::sun::star::uno::Reference< ::com::sun::star::accessibility::XAccessibleEventListener >& _rxListener
 110                     ) SAL_THROW( ( ) );
 111
 112         /** adds an event, which is to be braodcasted, to the queue
 113
 114             @param _nClient
 115                 the id of the client which needs to broadcast the event
 116         */
 117         static void addEvent(
 118                         const TClientId _nClient,
 119                         const ::com::sun::star::accessibility::AccessibleEventObject& _rEvent
 120                     ) SAL_THROW( ( ) );
 121
 122     };
 123
 124 //.........................................................................
 125 }   // namespace comphelper
 126 //.........................................................................
 127
 128 #endif // COMPHELPER_ACCESSIBLE_EVENT_NOTIFIER
 129
 130
 131 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */