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