include/comphelper/accessiblecomponenthelper.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_ACCESSIBLECOMPONENTHELPER_HXX
  21 #define INCLUDED_COMPHELPER_ACCESSIBLECOMPONENTHELPER_HXX
  22
  23 #include <com/sun/star/accessibility/XAccessibleComponent.hpp>
  24 #include <com/sun/star/accessibility/XAccessibleContext2.hpp>
  25 #include <com/sun/star/accessibility/XAccessibleEventBroadcaster.hpp>
  26 #include <com/sun/star/accessibility/XAccessibleExtendedComponent.hpp>
  27 #include <comphelper/accessibleeventnotifier.hxx>
  28 #include <cppuhelper/basemutex.hxx>
  29 #include <cppuhelper/compbase.hxx>
  30 #include <cppuhelper/implbase.hxx>
  31 #include <comphelper/uno3.hxx>
  32 #include <comphelper/comphelperdllapi.h>
  33
  34
  35 namespace comphelper
  36 {
  37
  38
  39     //= OCommonAccessibleComponent
  40
  41     typedef ::cppu::WeakComponentImplHelper <   css::accessibility::XAccessibleContext2,
  42                                                 css::accessibility::XAccessibleEventBroadcaster
  43                                             >   OCommonAccessibleComponent_Base;
  44
  45     /** base class encapsulating common functionality for the helper classes implementing
  46         the XAccessibleComponent respectively XAccessibleExtendendComponent
  47     */
  48     class COMPHELPER_DLLPUBLIC OCommonAccessibleComponent
  49                 :public ::cppu::BaseMutex
  50                 ,public OCommonAccessibleComponent_Base
  51     {
  52         friend class OContextEntryGuard;
  53     private:
  54         css::uno::WeakReference< css::accessibility::XAccessible > m_aCreator;         // the XAccessible which created our XAccessibleContext
  55         AccessibleEventNotifier::TClientId m_nClientId;
  56
  57     protected:
  58         virtual ~OCommonAccessibleComponent( ) override;
  59
  60         OCommonAccessibleComponent( );
  61
  62         /** late construction
  63         @param _rxAccessible
  64             the Accessible object which created this context.
  65             <p>If your derived implementation implements the XAccessible (and does not follow the proposed
  66             separation of XAccessible from XAccessibleContext), you may pass <code>this</code> here.</p>
  67
  68             <p>The object is hold weak, so its life time is not affected.</p>
  69
  70             <p>The object is needed for performance reasons: for <method>getAccessibleIndexInParent</method>,
  71             all children (which are XAccessible's theirself) of our parent have to be asked. If we know our
  72             XAccessible, we can compare it with all the children, instead of asking all children for their
  73             context and comparing this context with ourself.</p>
  74         */
  75         void    lateInit( const css::uno::Reference< css::accessibility::XAccessible >& _rxAccessible );
  76
  77         /** retrieves the creator previously set with <method>lateInit</method>
  78         */
  79         css::uno::Reference< css::accessibility::XAccessible >
  80                 getAccessibleCreator( ) const;
  81
  82     public:
  83         // XAccessibleEventBroadcaster
  84         virtual void SAL_CALL addAccessibleEventListener( const css::uno::Reference< css::accessibility::XAccessibleEventListener >& xListener ) override;
  85         virtual void SAL_CALL removeAccessibleEventListener( const css::uno::Reference< css::accessibility::XAccessibleEventListener >& xListener ) override;
  86
  87         // XAccessibleContext - still waiting to be overwritten
  88         virtual sal_Int64 SAL_CALL getAccessibleChildCount(  ) override = 0;
  89         virtual css::uno::Reference< css::accessibility::XAccessible > SAL_CALL getAccessibleChild( sal_Int64 i ) override = 0;
  90         virtual css::uno::Reference< css::accessibility::XAccessible > SAL_CALL getAccessibleParent(  ) override = 0;
  91         virtual sal_Int16 SAL_CALL getAccessibleRole(  ) override = 0;
  92         virtual OUString SAL_CALL getAccessibleDescription(  ) override = 0;
  93         virtual OUString SAL_CALL getAccessibleName(  ) override = 0;
  94         virtual css::uno::Reference< css::accessibility::XAccessibleRelationSet > SAL_CALL getAccessibleRelationSet(  ) override = 0;
  95         virtual sal_Int64 SAL_CALL getAccessibleStateSet(  ) override = 0;
  96
  97         // XAccessibleContext2 - default implementation
  98         virtual OUString SAL_CALL getAccessibleId(  ) override;
  99
 100         // XAccessibleContext - default implementations
 101         /** default implementation for retrieving the index of this object within the parent
 102             <p>This basic implementation here returns the index <code>i</code> of the child for which
 103                 <code>&lt;parent&gt;.getAccessibleChild( i )</code> equals our creator.</p>
 104         */
 105         virtual sal_Int64 SAL_CALL getAccessibleIndexInParent(  ) override;
 106         /** default implementation for retrieving the locale
 107             <p>This basic implementation returns the locale of the parent context,
 108             as retrieved via getAccessibleParent()->getAccessibleContext.</p>
 109         */
 110         virtual css::lang::Locale SAL_CALL getLocale(  ) override;
 111
 112     protected:
 113         // OComponentHelper
 114         virtual void SAL_CALL disposing() override;
 115
 116     protected:
 117         // helper
 118         /** notifies all AccessibleEventListeners of a certain event
 119
 120         @precond    not to be called with our mutex locked
 121         @param  _nEventId
 122             the id of the event. See AccessibleEventType
 123         @param  _rOldValue
 124             the old value to be notified
 125         @param  _rNewValue
 126             the new value to be notified
 127         */
 128         void NotifyAccessibleEvent(
 129                     const sal_Int16 _nEventId,
 130                     const css::uno::Any& _rOldValue,
 131                     const css::uno::Any& _rNewValue,
 132                     sal_Int32 nIndexHint = -1
 133                 );
 134
 135         // life time control
 136         /// checks whether the object is alive (returns <TRUE/> then) or disposed
 137         bool    isAlive() const;
 138         /// checks for being alive. If the object is already disposed (i.e. not alive), an exception is thrown.
 139         void        ensureAlive() const;
 140
 141         /** ensures that the object is disposed.
 142         @precond
 143             to be called from within the destructor of your derived class only!
 144         */
 145         void        ensureDisposed( );
 146
 147         /** shortcut for retrieving the context of the parent (returned by getAccessibleParent)
 148         */
 149         css::uno::Reference< css::accessibility::XAccessibleContext >
 150                     implGetParentContext();
 151
 152         // access to the base class' broadcast helper/mutex
 153         ::osl::Mutex&                   GetMutex()                  { return m_aMutex; }
 154
 155     protected:
 156         /// implements the calculation of the bounding rectangle - still waiting to be overwritten
 157         ///
 158         /// @throws css::uno::RuntimeException
 159         virtual css::awt::Rectangle implGetBounds(  ) = 0;
 160
 161     protected:
 162         /** non-virtual versions of the methods which can be implemented using <method>implGetBounds</method>
 163             note: getLocationOnScreen relies on a valid parent (XAccessibleContext::getParent()->getAccessibleContext()),
 164                  which itself implements XAccessibleComponent
 165
 166             @throws css::uno::RuntimeException
 167         */
 168         bool containsPoint( const css::awt::Point& aPoint );
 169         /// @throws css::uno::RuntimeException
 170         css::awt::Point getLocation(  );
 171         /// @throws css::uno::RuntimeException
 172         css::awt::Point getLocationOnScreen(  );
 173         /// @throws css::uno::RuntimeException
 174         css::awt::Size getSize(  );
 175         /// @throws css::uno::RuntimeException
 176         css::awt::Rectangle getBounds(  );
 177     };
 178
 179
 180     //= OAccessibleComponentHelper
 181
 182
 183     /** a helper class for implementing an AccessibleContext which at the same time
 184         supports an XAccessibleComponent interface.
 185     */
 186     class COMPHELPER_DLLPUBLIC OAccessibleComponentHelper
 187             :public cppu::ImplInheritanceHelper<
 188                  OCommonAccessibleComponent, css::accessibility::XAccessibleComponent>
 189     {
 190     private:
 191         OAccessibleComponentHelper(OAccessibleComponentHelper const &) = delete;
 192         OAccessibleComponentHelper(OAccessibleComponentHelper &&) = delete;
 193         void operator =(OAccessibleComponentHelper const &) = delete;
 194         void operator =(OAccessibleComponentHelper &&) = delete;
 195
 196     protected:
 197         OAccessibleComponentHelper();
 198
 199     public:
 200         // XAccessibleComponent - default implementations
 201         virtual sal_Bool SAL_CALL containsPoint( const css::awt::Point& aPoint ) override;
 202         virtual css::awt::Point SAL_CALL getLocation(  ) override;
 203         virtual css::awt::Point SAL_CALL getLocationOnScreen(  ) override;
 204         virtual css::awt::Size SAL_CALL getSize(  ) override;
 205         virtual css::awt::Rectangle SAL_CALL getBounds(  ) override;
 206     };
 207
 208
 209     //= OAccessibleExtendedComponentHelper
 210
 211
 212     /** a helper class for implementing an AccessibleContext which at the same time
 213         supports an XAccessibleExtendedComponent interface.
 214     */
 215     class COMPHELPER_DLLPUBLIC OAccessibleExtendedComponentHelper
 216             :public cppu::ImplInheritanceHelper<
 217                  OCommonAccessibleComponent, css::accessibility::XAccessibleExtendedComponent>
 218     {
 219     private:
 220         OAccessibleExtendedComponentHelper(OAccessibleExtendedComponentHelper const &) = delete;
 221         OAccessibleExtendedComponentHelper(OAccessibleExtendedComponentHelper &&) = delete;
 222         void operator =(OAccessibleExtendedComponentHelper const &) = delete;
 223         void operator =(OAccessibleExtendedComponentHelper &&) = delete;
 224
 225     protected:
 226         OAccessibleExtendedComponentHelper( );
 227
 228     public:
 229         // XAccessibleComponent - default implementations
 230         virtual sal_Bool SAL_CALL containsPoint( const css::awt::Point& aPoint ) override;
 231         virtual css::awt::Point SAL_CALL getLocation(  ) override;
 232         virtual css::awt::Point SAL_CALL getLocationOnScreen(  ) override;
 233         virtual css::awt::Size SAL_CALL getSize(  ) override;
 234         virtual css::awt::Rectangle SAL_CALL getBounds(  ) override;
 235     };
 236
 237
 238 }   // namespace comphelper
 239
 240
 241 #endif // INCLUDED_COMPHELPER_ACCESSIBLECOMPONENTHELPER_HXX
 242
 243
 244 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */