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