svx/source/accessibility/AccessibleParaManager.hxx

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: AccessibleParaManager.hxx,v $
  10  * $Revision: 1.12 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30
  31 #ifndef _SVX_ACCESSIBLE_PARA_MANAGER_HXX
  32 #define _SVX_ACCESSIBLE_PARA_MANAGER_HXX
  33
  34 #include <vector>
  35 #include <algorithm>
  36 #include <functional>
  37 #include <utility>
  38 #include <tools/gen.hxx>
  39 #include <com/sun/star/awt/Rectangle.hpp>
  40 #include <com/sun/star/uno/Reference.hxx>
  41 #include <cppuhelper/weakref.hxx>
  42 #include <com/sun/star/accessibility/XAccessibleContext.hpp>
  43
  44 class SvxEditSourceAdapter;
  45
  46 namespace accessibility
  47 {
  48     class AccessibleEditableTextPara;
  49
  50     /** Helper class for WeakCppRef
  51
  52         This class is returned by WeakChild::get() and contains a hard
  53         reference and a reference to the c++ object. This combination
  54         prevents the c++ object from destruction during usage. Hold
  55         this object only as long as absolutely necessary, prevents
  56         referenced object from vanishing otherwise
  57     */
  58     template < class UnoType, class CppType > class HardCppRef
  59     {
  60     public:
  61
  62         typedef UnoType UnoInterfaceType;
  63         typedef CppType InterfaceType;
  64
  65         HardCppRef( const ::com::sun::star::uno::WeakReference< UnoInterfaceType >& xRef, InterfaceType* rImpl ) :
  66             mxRef( xRef ),
  67             mpImpl( rImpl )
  68         {
  69         }
  70
  71         /** Query whether the reference is still valid.
  72
  73             Hands off also from the implementation pointer if this
  74             returns sal_False!
  75          */
  76         sal_Bool is() const { return mxRef.is(); }
  77         InterfaceType* operator->() const { return mpImpl; }
  78         InterfaceType& operator*() const { return *mpImpl; }
  79         ::com::sun::star::uno::Reference< UnoInterfaceType >& getRef() { return mxRef; }
  80         const ::com::sun::star::uno::Reference< UnoInterfaceType >& getRef() const { return mxRef; }
  81
  82         // default copy constructor and assignment will do
  83         // HardCppRef( const HardCppRef& );
  84         // HardCppRef& operator= ( const HardCppRef& );
  85
  86     private:
  87
  88         // the interface, hard reference to prevent object from vanishing
  89         ::com::sun::star::uno::Reference< UnoInterfaceType >    mxRef;
  90
  91         // the c++ object, for our internal stuff
  92         InterfaceType*                                                                                  mpImpl;
  93
  94     };
  95
  96     /** Helper class for weak object references plus implementation
  97
  98         This class combines a weak reference (to facilitate automatic
  99         object disposal if user drops last reference) and hard
 100         reference to the c++ class (for fast access and bypassing of
 101         the UNO interface)
 102     */
 103     template < class UnoType, class CppType > class WeakCppRef
 104     {
 105     public:
 106
 107         typedef UnoType UnoInterfaceType;
 108         typedef CppType InterfaceType;
 109         typedef HardCppRef< UnoInterfaceType, InterfaceType >  HardRefType;
 110
 111         WeakCppRef() : maWeakRef(), maUnsafeRef( NULL ) {}
 112         WeakCppRef( InterfaceType& rImpl ) :
 113             maWeakRef( ::com::sun::star::uno::Reference< UnoInterfaceType >( rImpl, ::com::sun::star::uno::UNO_QUERY ) ),
 114             maUnsafeRef( &rImpl )
 115         {
 116         }
 117
 118         WeakCppRef( HardRefType& rImpl ) :
 119             maWeakRef( rImpl.getRef() ),
 120             maUnsafeRef( rImpl.operator->() )
 121         {
 122         }
 123
 124         // get object with c++ object and hard reference (which
 125         // prevents the c++ object from destruction during use)
 126         HardRefType get() const { return HardRefType( maWeakRef, maUnsafeRef ); }
 127
 128         // default copy constructor and assignment will do
 129         // WeakCppRef( const WeakCppRef& );
 130         // WeakCppRef& operator= ( const WeakCppRef& );
 131
 132     private:
 133
 134         // the interface, hold weakly
 135         ::com::sun::star::uno::WeakReference< UnoInterfaceType >        maWeakRef;
 136
 137         // hard ref to c++ class, _only_ valid if maWeakRef.is() is true
 138         InterfaceType*                                                                                          maUnsafeRef;
 139     };
 140
 141
 142     /** This class manages the paragraphs of an AccessibleTextHelper
 143
 144         To facilitate automatic deletion of paragraphs no longer used,
 145         this class uses the WeakCppRef helper to hold the objects weakly.
 146      */
 147     class AccessibleParaManager
 148     {
 149     public:
 150         typedef WeakCppRef < ::com::sun::star::accessibility::XAccessible, AccessibleEditableTextPara > WeakPara;
 151         typedef ::std::pair< WeakPara, ::com::sun::star::awt::Rectangle > WeakChild;
 152         typedef ::std::pair< ::com::sun::star::uno::Reference<
 153             ::com::sun::star::accessibility::XAccessible > , ::com::sun::star::awt::Rectangle > Child;
 154         typedef ::std::vector< WeakChild > VectorOfChildren;
 155         typedef ::std::vector< sal_Int16 > VectorOfStates;
 156
 157         AccessibleParaManager();
 158         ~AccessibleParaManager();
 159
 160         /** Sets a vector of additional accessible states.
 161
 162             The states are passed to every created child object
 163             (text paragraph). The state values are defined in
 164             com::sun::star::accessibility::AccessibleStateType.
 165          */
 166         void SetAdditionalChildStates( const VectorOfStates& rChildStates );
 167
 168         /** Returns the additional accessible states for children.
 169          */
 170         const VectorOfStates& GetAdditionalChildStates() const;
 171
 172         /** Set the number of paragraphs
 173
 174             @param nNumPara
 175             The total number of paragraphs the EditEngine currently
 176             has (_not_ the number of currently visible children)
 177          */
 178         void SetNum( sal_Int32 nNumParas );
 179
 180         /** Get the number of paragraphs currently possible */
 181         sal_uInt32 GetNum() const;
 182
 183         // iterators
 184         VectorOfChildren::iterator begin();
 185         VectorOfChildren::iterator end();
 186         VectorOfChildren::const_iterator begin() const;
 187         VectorOfChildren::const_iterator end() const;
 188
 189         // dealing with single paragraphs (release reference, return reference etc)
 190         void Release( sal_uInt32 nPara );
 191         /// Set focus to given child
 192         void SetFocus( sal_Int32 nChild );
 193
 194         void FireEvent( sal_uInt32 nPara,
 195                         const sal_Int16 nEventId,
 196                         const ::com::sun::star::uno::Any& rNewValue = ::com::sun::star::uno::Any(),
 197                         const ::com::sun::star::uno::Any& rOldValue = ::com::sun::star::uno::Any() ) const;
 198
 199         static sal_Bool IsReferencable( WeakPara::HardRefType aChild );
 200         sal_Bool IsReferencable( sal_uInt32 nChild ) const;
 201         static void ShutdownPara( const WeakChild& rChild );
 202
 203         Child CreateChild( sal_Int32                                                                                                                                                                            nChild,
 204                            const ::com::sun::star::uno::Reference< ::com::sun::star::accessibility::XAccessible >& xFrontEnd,
 205                            SvxEditSourceAdapter&                                                                                                                                                        rEditSource,
 206                            sal_uInt32                                                                                                                                                                           nParagraphIndex );
 207
 208         WeakChild GetChild( sal_uInt32 nParagraphIndex ) const;
 209
 210         // forwarder to all paragraphs
 211         /// Make all children active and editable (or off)
 212         void SetActive( sal_Bool bActive = sal_True );
 213         /// Set state of all children
 214         void SetState( const sal_Int16 nStateId );
 215         /// Unset state of all children
 216         void UnSetState( const sal_Int16 nStateId );
 217         /// Set offset to edit engine for all children
 218         void SetEEOffset                ( const Point& rOffset );
 219         /// Change edit source on all living children
 220         void SetEditSource              ( SvxEditSourceAdapter* pEditSource );
 221         /// Dispose all living children
 222         void Dispose                    ();
 223
 224         // forwarder to given paragraphs
 225         //------------------------------------------------------------------------
 226         /** Release the given range of paragraphs
 227
 228             All ranges have the meaning [start,end), similar to STL
 229
 230             @param nStartPara
 231             Index of paragraph to start with releasing
 232
 233             @param nEndPara
 234             Index of first paragraph to stop with releasing
 235          */
 236         void Release( sal_uInt32 nStartPara, sal_uInt32 nEndPara );
 237
 238         /** Fire event for the given range of paragraphs
 239
 240             All ranges have the meaning [start,end), similar to STL
 241
 242             @param nStartPara
 243             Index of paragraph to start with event firing
 244
 245             @param nEndPara
 246             Index of first paragraph to stop with event firing
 247          */
 248         void FireEvent( sal_uInt32 nStartPara,
 249                         sal_uInt32 nEndPara,
 250                         const sal_Int16 nEventId,
 251                         const ::com::sun::star::uno::Any& rNewValue = ::com::sun::star::uno::Any(),
 252                         const ::com::sun::star::uno::Any& rOldValue = ::com::sun::star::uno::Any() ) const;
 253
 254         /** Functor adapter for ForEach template
 255
 256             Adapts giving functor such that only the paragraph objects
 257             are accessed and the fact that our children are held
 258             weakly is hidden
 259
 260             The functor must provide the following method:
 261             void operator() ( AccessibleEditablePara& )
 262
 263         */
 264         template < typename Functor > class WeakChildAdapter : public ::std::unary_function< const WeakChild&, void >
 265         {
 266         public:
 267             WeakChildAdapter( Functor& rFunctor ) : mrFunctor(rFunctor) {}
 268             void operator()( const WeakChild& rPara )
 269             {
 270                 // retrieve hard reference from weak one
 271                 WeakPara::HardRefType aHardRef( rPara.first.get() );
 272
 273                 if( aHardRef.is() )
 274                     mrFunctor( *aHardRef );
 275             }
 276
 277         private:
 278             Functor& mrFunctor;
 279         };
 280
 281         /** Adapter for unary member functions
 282
 283             Since STL's binder don't work with const& arguments (and
 284             BOOST's neither, at least on MSVC), have to provide our
 285             own adapter for unary member functions.
 286
 287             Create with pointer to member function of
 288             AccessibleEditableTextPara and the corresponding argument.
 289          */
 290         template < typename Argument > class MemFunAdapter : public ::std::unary_function< const WeakChild&, void >
 291         {
 292         public:
 293             typedef void (::accessibility::AccessibleEditableTextPara::*FunctionPointer)( Argument );
 294
 295             MemFunAdapter( FunctionPointer aFunPtr, Argument aArg ) : maFunPtr(aFunPtr), maArg(aArg) {}
 296             void operator()( const WeakChild& rPara )
 297             {
 298                 // retrieve hard reference from weak one
 299                 WeakPara::HardRefType aHardRef( rPara.first.get() );
 300
 301                 if( aHardRef.is() )
 302                     (*aHardRef.*maFunPtr)( maArg );
 303             }
 304
 305         private:
 306             FunctionPointer maFunPtr;
 307             Argument maArg;
 308         };
 309
 310         /** Generic algorithm on given paragraphs
 311
 312             Convenience method, that already adapts the given functor with WeakChildAdapter
 313         */
 314         template < typename Functor > void ForEach( Functor& rFunctor )
 315         {
 316             ::std::for_each( begin(), end(), WeakChildAdapter< Functor >(rFunctor) );
 317         }
 318
 319     private:
 320         /// Set state on given child
 321         void SetState( sal_Int32 nChild, const sal_Int16 nStateId );
 322         /// Unset state on given child
 323         void UnSetState( sal_Int32 nChild, const sal_Int16 nStateId );
 324         /// Init child with default state (as stored in previous SetFocus and SetActive calls)
 325         void InitChild( AccessibleEditableTextPara&     rChild,
 326                         SvxEditSourceAdapter&                   rEditSource,
 327                         sal_Int32                                               nChild,
 328                         sal_uInt32                                              nParagraphIndex ) const;
 329
 330         // vector the size of the paragraph number of the underlying EditEngine
 331         VectorOfChildren maChildren;
 332
 333         /// Additional states that will be set at every created child object.
 334         VectorOfStates maChildStates;
 335
 336         // cache EE offset for child creation
 337         Point maEEOffset;
 338
 339         // which child currently has the focus (-1 for none)
 340         sal_Int32 mnFocusedChild;
 341
 342         // whether children are active and editable
 343         sal_Bool mbActive;
 344     };
 345
 346 } // end of namespace accessibility
 347
 348 #endif
 349