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