include/comphelper/accessiblecontexthelper.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_ACCESSIBLECONTEXTHELPER_HXX
  21 #define INCLUDED_COMPHELPER_ACCESSIBLECONTEXTHELPER_HXX
  22
  23 #include <cppuhelper/compbase2.hxx>
  24 #include <cppuhelper/basemutex.hxx>
  25 #include <com/sun/star/accessibility/XAccessibleContext2.hpp>
  26 #include <com/sun/star/accessibility/XAccessibleEventBroadcaster.hpp>
  27 #include <comphelper/comphelperdllapi.h>
  28 #include <comphelper/solarmutex.hxx>
  29 #include <memory>
  30
  31
  32 namespace comphelper
  33 {
  34
  35
  36     //= OAccessibleContextHelper
  37
  38
  39     class OContextHelper_Impl;
  40     typedef ::cppu::WeakAggComponentImplHelper2 <   css::accessibility::XAccessibleContext2,
  41                                                     css::accessibility::XAccessibleEventBroadcaster
  42                                                 >   OAccessibleContextHelper_Base;
  43
  44     /** helper class for implementing an AccessibleContext
  45     */
  46     class COMPHELPER_DLLPUBLIC OAccessibleContextHelper
  47                 :public ::cppu::BaseMutex
  48                 ,public OAccessibleContextHelper_Base
  49     {
  50         friend class OContextEntryGuard;
  51     private:
  52         std::unique_ptr<OContextHelper_Impl>    m_pImpl;
  53
  54     protected:
  55         virtual ~OAccessibleContextHelper( ) override;
  56
  57         OAccessibleContextHelper( );
  58
  59         /** late construction
  60         @param _rxAccessible
  61             the Accessible object which created this context.
  62             <p>If your derived implementation implements the XAccessible (and does not follow the proposed
  63             separation of XAccessible from XAccessibleContext), you may pass <code>this</code> here.</p>
  64
  65             <p>The object is hold weak, so its life time is not affected.</p>
  66
  67             <p>The object is needed for performance reasons: for <method>getAccessibleIndexInParent</method>,
  68             all children (which are XAccessible's theirself) of our parent have to be asked. If we know our
  69             XAccessible, we can compare it with all the children, instead of asking all children for their
  70             context and comparing this context with ourself.</p>
  71         */
  72         void    lateInit( const css::uno::Reference< css::accessibility::XAccessible >& _rxAccessible );
  73
  74         /** retrieves the creator previously set with <method>lateInit</method>
  75         */
  76         css::uno::Reference< css::accessibility::XAccessible >
  77                 getAccessibleCreator( ) const;
  78
  79     public:
  80         // XAccessibleEventBroadcaster
  81         virtual void SAL_CALL addAccessibleEventListener( const css::uno::Reference< css::accessibility::XAccessibleEventListener >& xListener ) override;
  82         virtual void SAL_CALL removeAccessibleEventListener( const css::uno::Reference< css::accessibility::XAccessibleEventListener >& xListener ) override;
  83
  84         // XAccessibleContext - still waiting to be overwritten
  85         virtual sal_Int32 SAL_CALL getAccessibleChildCount(  ) override = 0;
  86         virtual css::uno::Reference< css::accessibility::XAccessible > SAL_CALL getAccessibleChild( sal_Int32 i ) override = 0;
  87         virtual css::uno::Reference< css::accessibility::XAccessible > SAL_CALL getAccessibleParent(  ) override = 0;
  88         virtual sal_Int16 SAL_CALL getAccessibleRole(  ) override = 0;
  89         virtual OUString SAL_CALL getAccessibleDescription(  ) override = 0;
  90         virtual OUString SAL_CALL getAccessibleName(  ) override = 0;
  91         virtual css::uno::Reference< css::accessibility::XAccessibleRelationSet > SAL_CALL getAccessibleRelationSet(  ) override = 0;
  92         virtual css::uno::Reference< css::accessibility::XAccessibleStateSet > SAL_CALL getAccessibleStateSet(  ) override = 0;
  93
  94         // XAccessibleContext2 - default implementation
  95         virtual OUString SAL_CALL getAccessibleId(  ) override;
  96
  97         // XAccessibleContext - default implementations
  98         /** default implementation for retrieving the index of this object within the parent
  99             <p>This basic implementation here returns the index <code>i</code> of the child for which
 100                 <code>&lt;parent&gt;.getAccessibleChild( i )</code> equals our creator.</p>
 101         */
 102         virtual sal_Int32 SAL_CALL getAccessibleIndexInParent(  ) override;
 103         /** default implementation for retrieving the locale
 104             <p>This basic implementation returns the locale of the parent context,
 105             as retrieved via getAccessibleParent()->getAccessibleContext.</p>
 106         */
 107         virtual css::lang::Locale SAL_CALL getLocale(  ) override;
 108
 109     protected:
 110         // OComponentHelper
 111         virtual void SAL_CALL disposing() override;
 112
 113     protected:
 114         // helper
 115         /** notifies all AccessibleEventListeners of a certain event
 116
 117         @precond    not to be called with our mutex locked
 118         @param  _nEventId
 119             the id of the event. See AccessibleEventType
 120         @param  _rOldValue
 121             the old value to be notified
 122         @param  _rNewValue
 123             the new value to be notified
 124         */
 125         void NotifyAccessibleEvent(
 126                     const sal_Int16 _nEventId,
 127                     const css::uno::Any& _rOldValue,
 128                     const css::uno::Any& _rNewValue
 129                 );
 130
 131         // life time control
 132         /// checks whether the object is alive (returns <TRUE/> then) or disposed
 133         bool    isAlive() const;
 134         /// checks for being alive. If the object is already disposed (i.e. not alive), an exception is thrown.
 135         void        ensureAlive() const;
 136
 137         /** ensures that the object is disposed.
 138         @precond
 139             to be called from within the destructor of your derived class only!
 140         */
 141         void        ensureDisposed( );
 142
 143         /** shortcut for retrieving the context of the parent (returned by getAccessibleParent)
 144         */
 145         css::uno::Reference< css::accessibility::XAccessibleContext >
 146                     implGetParentContext();
 147
 148         // access to the base class' broadcast helper/mutex
 149         ::osl::Mutex&                   GetMutex()                  { return m_aMutex; }
 150     };
 151
 152
 153     //= OContextEntryGuard
 154
 155     /** helper class for guarding the entry into OAccessibleContextHelper methods.
 156
 157         <p>The class has two responsibilities:
 158         <ul><li>it locks the mutex of an OAccessibleContextHelper instance, as long as the guard lives</li>
 159             <li>it checks if a given OAccessibleContextHelper instance is alive, else an exception is thrown
 160                 our of the constructor of the guard</li>
 161         </ul>
 162         <br/>
 163         This makes it your first choice (hopefully :) for guarding any interface method implementations of
 164         you derived class.
 165         </p>
 166     */
 167     class OContextEntryGuard : public ::osl::ClearableMutexGuard
 168     {
 169     public:
 170         /** constructs the guard
 171
 172             <p>The given context (it's mutex, respectively) is locked, and an exception is thrown if the context
 173             is not alive anymore. In the latter case, of course, the mutex is freed, again.</p>
 174
 175         @param _pContext
 176             the context which shall be guarded
 177         @precond <arg>_pContext</arg> != NULL
 178         */
 179         inline OContextEntryGuard( OAccessibleContextHelper* _pContext );
 180     };
 181
 182
 183     inline OContextEntryGuard::OContextEntryGuard( OAccessibleContextHelper* _pContext  )
 184         : ::osl::ClearableMutexGuard( _pContext->GetMutex() )
 185     {
 186         _pContext->ensureAlive();
 187     }
 188
 189
 190     //= OExternalLockGuard
 191
 192     class OExternalLockGuard
 193             :public osl::Guard<SolarMutex>
 194             ,public OContextEntryGuard
 195     {
 196     public:
 197         inline OExternalLockGuard( OAccessibleContextHelper* _pContext );
 198     };
 199
 200
 201     inline OExternalLockGuard::OExternalLockGuard( OAccessibleContextHelper* _pContext )
 202         :osl::Guard<SolarMutex>( SolarMutex::get() )
 203         ,OContextEntryGuard( _pContext )
 204     {
 205         // Only lock the external mutex,
 206         // release the ::osl::Mutex of the OAccessibleContextHelper instance.
 207         // If you call into another UNO object with locked ::osl::Mutex,
 208         // this may lead to dead locks.
 209         clear();
 210     }
 211
 212
 213 }   // namespace comphelper
 214
 215
 216 #endif // INCLUDED_COMPHELPER_ACCESSIBLECONTEXTHELPER_HXX
 217
 218
 219 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */