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