include/comphelper/accessiblewrapper.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_ACCESSIBLEWRAPPER_HXX
  21 #define INCLUDED_COMPHELPER_ACCESSIBLEWRAPPER_HXX
  22
  23 #include <sal/config.h>
  24
  25 #include <map>
  26
  27 #include <comphelper/proxyaggregation.hxx>
  28 #include <com/sun/star/accessibility/XAccessible.hpp>
  29 #include <com/sun/star/accessibility/XAccessibleContext.hpp>
  30 #include <com/sun/star/accessibility/XAccessibleEventBroadcaster.hpp>
  31 #include <com/sun/star/accessibility/XAccessibleEventListener.hpp>
  32 #include <cppuhelper/compbase.hxx>
  33 #include <com/sun/star/lang/XComponent.hpp>
  34 #include <cppuhelper/implbase.hxx>
  35 #include <cppuhelper/implbase1.hxx>
  36 #include <cppuhelper/basemutex.hxx>
  37 #include <comphelper/sequence.hxx>
  38 #include <comphelper/uno3.hxx>
  39 #include <cppuhelper/interfacecontainer.hxx>
  40 #include <comphelper/accessibleeventnotifier.hxx>
  41 #include <comphelper/stl_types.hxx>
  42 #include <comphelper/comphelperdllapi.h>
  43 #include <rtl/ref.hxx>
  44
  45
  46 namespace comphelper
  47 {
  48
  49
  50     //= OAccessibleWrapper
  51
  52
  53     class OAccessibleContextWrapper;
  54     class OWrappedAccessibleChildrenManager;
  55
  56     struct OAccessibleWrapper_Base :
  57         public ::cppu::ImplHelper1 < css::accessibility::XAccessible >
  58     {
  59     protected:
  60         ~OAccessibleWrapper_Base() {}
  61     };
  62
  63     /** a class which aggregates a proxy for an XAccessible, and wrapping the context returned by this
  64         XAccessible.
  65     */
  66     class COMPHELPER_DLLPUBLIC OAccessibleWrapper:public OAccessibleWrapper_Base
  67                             ,public OComponentProxyAggregation
  68
  69     {
  70     private:
  71         css::uno::Reference< css::accessibility::XAccessible >
  72                 m_xParentAccessible;
  73         css::uno::WeakReference< css::accessibility::XAccessibleContext >
  74                 m_aContext;
  75
  76     protected:
  77         css::uno::Reference< css::accessibility::XAccessible >
  78                 m_xInnerAccessible;
  79
  80     public:
  81         /** ctor
  82             @param _rxContext
  83                 a service factory
  84
  85             @param _rxInnerAccessible
  86                 the object to wrap
  87
  88             @param _rxParentAccessible
  89                 The XAccessible which is our parent
  90         */
  91         OAccessibleWrapper(
  92             const css::uno::Reference< css::uno::XComponentContext >&     _rxContext,
  93             const css::uno::Reference< css::accessibility::XAccessible >& _rxInnerAccessible,
  94             const css::uno::Reference< css::accessibility::XAccessible >& _rxParentAccessible
  95         );
  96         DECLARE_XINTERFACE()
  97         DECLARE_XTYPEPROVIDER()
  98
  99         // returns the context without creating it
 100         css::uno::Reference< css::accessibility::XAccessibleContext >
 101                     getContextNoCreate( ) const;
 102
 103     protected:
 104         virtual css::uno::Reference< css::accessibility::XAccessibleContext > SAL_CALL
 105                     getAccessibleContext(  ) override;
 106
 107         const css::uno::Reference< css::accessibility::XAccessible >&
 108                     getParent() const { return m_xParentAccessible; }
 109
 110         // own overridables
 111         virtual OAccessibleContextWrapper* createAccessibleContext(
 112                 const css::uno::Reference< css::accessibility::XAccessibleContext >& _rxInnerContext
 113             );
 114
 115     protected:
 116         virtual ~OAccessibleWrapper( ) override;
 117
 118     private:
 119         OAccessibleWrapper( const OAccessibleWrapper& ) = delete;
 120         OAccessibleWrapper& operator=( const OAccessibleWrapper& ) = delete;
 121     };
 122
 123
 124     //= OAccessibleContextWrapperHelper
 125
 126
 127     typedef ::cppu::ImplHelper1 <   css::accessibility::XAccessibleEventListener
 128                                 >   OAccessibleContextWrapperHelper_Base;
 129
 130     /** Helper for wrapping an XAccessibleContext by aggregating a proxy for it.
 131
 132         <p>This class does not have own ref counting. In addition, it does not implement
 133         the XAccessibleContext interface, but provides all the methods from this interface
 134         which must be implemented using the inner context (such as getAccessibleChild*).</p>
 135
 136         <p>Children of the aggregated XAccessibleContext are wrapped, too.</p>
 137
 138         <p>AccessibleEvents fired by the inner context are multiplexed, especially, any references to
 139         children in such events are translated. This means that even in such events, no un-wrapped object
 140         will ever leave this class - if the aggregated context notifies an child event, the child passed
 141         to the event is wrapped</p>
 142
 143         @seealso OAccessibleContextWrapper
 144     */
 145     class COMPHELPER_DLLPUBLIC OAccessibleContextWrapperHelper
 146                 :private OComponentProxyAggregationHelper
 147                 ,public OAccessibleContextWrapperHelper_Base
 148     {
 149     protected:
 150         /// the context we're wrapping (properly typed, in opposite to OComponentProxyAggregationHelper::m_xInner)
 151         css::uno::Reference< css::accessibility::XAccessibleContext >
 152                                                             m_xInnerContext;
 153         /// the XAccessible which created this context
 154         css::uno::Reference< css::accessibility::XAccessible >
 155                                                             m_xOwningAccessible;
 156         /// the XAccessible which is to be returned in getAccessibleParent
 157         css::uno::Reference< css::accessibility::XAccessible >
 158                                                             m_xParentAccessible;
 159
 160         rtl::Reference<OWrappedAccessibleChildrenManager>   m_xChildMapper;     // for mapping children from our inner context to our callers
 161
 162     protected:
 163         /** ctor
 164
 165             @param _rxContext
 166                 a service factory
 167
 168             @param _rxInnerAccessibleContext
 169                 the object to wrap
 170
 171             @param _rxOwningAccessible
 172                 The XAccessible which created this object. This is necessary because children
 173                 of our wrapped context need to be wrapped, too, and if they're asked for a parent,
 174                 they of course should return the proper parent<br/>
 175                 The object will be held with a hard reference
 176
 177             @param _rxParentAccessible
 178                 The XAccessible to return in the getAccessibleParent call
 179         */
 180         OAccessibleContextWrapperHelper(
 181             const css::uno::Reference< css::uno::XComponentContext >& _rxContext,
 182             ::cppu::OBroadcastHelper& _rBHelper,
 183             const css::uno::Reference< css::accessibility::XAccessibleContext >& _rxInnerAccessibleContext,
 184             const css::uno::Reference< css::accessibility::XAccessible >& _rxOwningAccessible,
 185             const css::uno::Reference< css::accessibility::XAccessible >& _rxParentAccessible
 186         );
 187
 188         /// to be called from within your ctor - does the aggregation of a proxy for m_xInnerContext
 189         void aggregateProxy(
 190             oslInterlockedCount& _rRefCount,
 191             ::cppu::OWeakObject& _rDelegator
 192         );
 193
 194     protected:
 195         // XInterface
 196         css::uno::Any SAL_CALL queryInterface( const css::uno::Type& _rType ) override;
 197
 198         // XTypeProvider
 199         DECLARE_XTYPEPROVIDER( )
 200
 201         // XAccessibleContext
 202         /// @throws css::uno::RuntimeException
 203         sal_Int32 baseGetAccessibleChildCount(  );
 204         /// @throws css::lang::IndexOutOfBoundsException
 205         /// @throws css::uno::RuntimeException
 206         css::uno::Reference< css::accessibility::XAccessible > baseGetAccessibleChild( sal_Int32 i );
 207         /// @throws css::uno::RuntimeException
 208         css::uno::Reference< css::accessibility::XAccessibleRelationSet > baseGetAccessibleRelationSet(  );
 209
 210         // XAccessibleEventListener
 211         virtual void SAL_CALL notifyEvent( const css::accessibility::AccessibleEventObject& aEvent ) override;
 212
 213         // XEventListener
 214         virtual void SAL_CALL disposing( const css::lang::EventObject& Source ) override;
 215
 216         // XComponent/OComponentProxyAggregationHelper
 217         virtual void SAL_CALL dispose() override;
 218
 219         // own overridables
 220         /** notify an accessible event which has been translated (if necessary)
 221
 222             <p>Usually, you derive your class from both OAccessibleContextWrapperHelper and XAccessibleEventBroadcaster,
 223             and simply call all your XAccessibleEventListener with the given event.</p>
 224
 225             <p>The mutex of the BroadcastHelper passed to the instance's ctor is <em>not</em> locked when calling
 226             into this method</p>
 227
 228             @throws css::uno::RuntimeException
 229         */
 230         virtual void notifyTranslatedEvent( const css::accessibility::AccessibleEventObject& _rEvent ) = 0;
 231
 232     protected:
 233         virtual ~OAccessibleContextWrapperHelper( ) override;
 234
 235         OAccessibleContextWrapperHelper(const OAccessibleContextWrapperHelper&) = delete;
 236         OAccessibleContextWrapperHelper& operator=(const OAccessibleContextWrapperHelper&) = delete;
 237     };
 238
 239
 240     //= OAccessibleContextWrapper
 241
 242     typedef ::cppu::WeakComponentImplHelper<    css::accessibility::XAccessibleEventBroadcaster
 243                                             ,   css::accessibility::XAccessibleContext
 244                                             >   OAccessibleContextWrapper_CBase;
 245
 246     class COMPHELPER_DLLPUBLIC OAccessibleContextWrapper
 247                     :public cppu::BaseMutex
 248                     ,public OAccessibleContextWrapper_CBase
 249                     ,public OAccessibleContextWrapperHelper
 250     {
 251     private:
 252         ::comphelper::AccessibleEventNotifier::TClientId    m_nNotifierClient;      // for notifying AccessibleEvents
 253
 254     public:
 255         /** ctor
 256
 257             @param _rxContext
 258                 a service factory
 259
 260             @param _rxInnerAccessibleContext
 261                 the object to wrap
 262
 263             @param _rxOwningAccessible
 264                 The XAccessible which created this object. This is necessary because children
 265                 of our wrapped context need to be wrapped, too, and if they're asked for a parent,
 266                 they of course should return the proper parent<br/>
 267                 The object will be held with a hard reference
 268
 269             @param _rxParentAccessible
 270                 The XAccessible to return in the getAccessibleParent call
 271         */
 272         OAccessibleContextWrapper(
 273             const css::uno::Reference< css::uno::XComponentContext >& _rxContext,
 274             const css::uno::Reference< css::accessibility::XAccessibleContext >& _rxInnerAccessibleContext,
 275             const css::uno::Reference< css::accessibility::XAccessible >& _rxOwningAccessible,
 276             const css::uno::Reference< css::accessibility::XAccessible >& _rxParentAccessible
 277         );
 278
 279         // XInterface
 280         DECLARE_XINTERFACE( )
 281         // XTypeProvider
 282         DECLARE_XTYPEPROVIDER( )
 283
 284         // XAccessibleContext
 285         virtual sal_Int32 SAL_CALL getAccessibleChildCount(  ) override;
 286         virtual css::uno::Reference< css::accessibility::XAccessible > SAL_CALL getAccessibleChild( sal_Int32 i ) override;
 287         virtual css::uno::Reference< css::accessibility::XAccessible > SAL_CALL getAccessibleParent(  ) override;
 288         virtual sal_Int32 SAL_CALL getAccessibleIndexInParent(  ) override;
 289         virtual sal_Int16 SAL_CALL getAccessibleRole(  ) override;
 290         virtual OUString SAL_CALL getAccessibleDescription(  ) override;
 291         virtual OUString SAL_CALL getAccessibleName(  ) override;
 292         virtual css::uno::Reference< css::accessibility::XAccessibleRelationSet > SAL_CALL getAccessibleRelationSet(  ) override;
 293         virtual css::uno::Reference< css::accessibility::XAccessibleStateSet > SAL_CALL getAccessibleStateSet(  ) override;
 294         virtual css::lang::Locale SAL_CALL getLocale(  ) override;
 295
 296         // XAccessibleEventBroadcaster
 297         virtual void SAL_CALL addAccessibleEventListener( const css::uno::Reference< css::accessibility::XAccessibleEventListener >& xListener ) override;
 298         virtual void SAL_CALL removeAccessibleEventListener( const css::uno::Reference< css::accessibility::XAccessibleEventListener >& xListener ) override;
 299
 300         // OAccessibleContextWrapper
 301         virtual void notifyTranslatedEvent( const css::accessibility::AccessibleEventObject& _rEvent ) override;
 302
 303         // OComponentHelper
 304         using OAccessibleContextWrapperHelper::disposing;
 305         virtual void SAL_CALL disposing() override;
 306
 307     protected:
 308         virtual ~OAccessibleContextWrapper() override;
 309
 310     private:
 311         OAccessibleContextWrapper( const OAccessibleContextWrapper& ) = delete;
 312         OAccessibleContextWrapper& operator=( const OAccessibleContextWrapper& ) = delete;
 313     };
 314
 315
 316     //= OWrappedAccessibleChildrenManager
 317
 318
 319     typedef ::std::map  <   css::uno::Reference< css::accessibility::XAccessible >
 320                         ,   css::uno::Reference< css::accessibility::XAccessible >
 321                         ,   OInterfaceCompare< css::accessibility::XAccessible >
 322                         >   AccessibleMap;
 323                         // TODO: think about if we should hold these objects weak
 324
 325     typedef ::cppu::WeakImplHelper<   css::lang::XEventListener
 326                                   >   OWrappedAccessibleChildrenManager_Base;
 327     /** manages wrapping XAccessible's to XAccessible's
 328     */
 329     class COMPHELPER_DLLPUBLIC OWrappedAccessibleChildrenManager : public OWrappedAccessibleChildrenManager_Base
 330     {
 331     protected:
 332         css::uno::Reference< css::uno::XComponentContext >
 333                                 m_xContext;
 334         css::uno::WeakReference< css::accessibility::XAccessible >
 335                                 m_aOwningAccessible;    // the XAccessible which belongs to the XAccessibleContext which we work for
 336         AccessibleMap           m_aChildrenMap;         // for caching children
 337         bool                    m_bTransientChildren;   // are we prohibited to cache our children?
 338
 339     public:
 340         /// ctor
 341         OWrappedAccessibleChildrenManager(
 342             const css::uno::Reference< css::uno::XComponentContext >& _rxContext
 343         );
 344
 345         /** specifies if the children are to be considered transient (i.e.: not cached)
 346             <p>to be called only once per lifetime</p>
 347         */
 348         void    setTransientChildren( bool _bSet );
 349
 350         /** sets the XAccessible which belongs to the XAccessibleContext which we work for
 351             <p>to be called only once per lifetime</p>
 352         */
 353         void    setOwningAccessible( const css::uno::Reference< css::accessibility::XAccessible >& _rxAcc );
 354
 355         /// retrieves a wrapper for the given accessible
 356         css::uno::Reference< css::accessibility::XAccessible >
 357                 getAccessibleWrapperFor(
 358                     const css::uno::Reference< css::accessibility::XAccessible >& _rxKey
 359                 );
 360
 361         /// erases the given key from the map (if it is present there)
 362         void    removeFromCache( const css::uno::Reference< css::accessibility::XAccessible >& _rxKey );
 363
 364         /// invalidates (i.e. empties) the map
 365         void    invalidateAll( );
 366
 367         /** disposes (i.e. cleares) the manager
 368
 369             <p>Note that the XAccessibleContext's of the mapped XAccessible objects are disposed, too.</p>
 370         */
 371         void    dispose();
 372
 373         /** handles a notification as got from the parent of the children we're managing
 374             <p>This applies only to the notifications which have a direct impact on our map.</p>
 375         */
 376         void    handleChildNotification( const css::accessibility::AccessibleEventObject& _rEvent );
 377
 378         /** translates events as got from the parent of the children we're managing
 379             <p>This applies only to the notifications which deal with child objects which we manage.</p>
 380         */
 381         void    translateAccessibleEvent(
 382             const   css::accessibility::AccessibleEventObject& _rEvent,
 383                     css::accessibility::AccessibleEventObject& _rTranslatedEvent
 384         );
 385
 386     protected:
 387         // XEventListener
 388         virtual void SAL_CALL disposing( const css::lang::EventObject& Source ) override;
 389
 390     protected:
 391         void    implTranslateChildEventValue( const css::uno::Any& _rInValue, css::uno::Any& _rOutValue );
 392
 393     protected:
 394         virtual ~OWrappedAccessibleChildrenManager( ) override;
 395
 396     private:
 397         OWrappedAccessibleChildrenManager( const OWrappedAccessibleChildrenManager& ) = delete;
 398         OWrappedAccessibleChildrenManager& operator=( const OWrappedAccessibleChildrenManager& ) = delete;
 399     };
 400
 401
 402 }   // namespace accessibility
 403
 404
 405 #endif // INCLUDED_COMPHELPER_ACCESSIBLEWRAPPER_HXX
 406
 407 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */