binfilter/inc/bf_svx/AccessibleStaticTextBase.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: AccessibleStaticTextBase.hxx,v $
  10  * $Revision: 1.6 $
  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_ACCESSILE_STATIC_TEXT_BASE_HXX_
  32 #define _SVX_ACCESSILE_STATIC_TEXT_BASE_HXX_
  33
  34 #include <memory>
  35
  36 #ifndef _SV_GEN_HXX
  37 #include <tools/gen.hxx>
  38 #endif
  39
  40
  41
  42 #ifndef _COM_SUN_STAR_ACCESSIBILITY_XACCESSIBLE_HPP_
  43 #include <com/sun/star/accessibility/XAccessible.hpp>
  44 #endif
  45
  46 #ifndef _COM_SUN_STAR_ACCESSIBILITY_XACCESSIBLETEXT_HPP_
  47 #include <com/sun/star/accessibility/XAccessibleText.hpp>
  48 #endif
  49
  50 namespace binfilter {
  51
  52 class SvxEditSource;
  53
  54 namespace accessibility
  55 {
  56
  57     class AccessibleStaticTextBase_Impl;
  58
  59     /** Helper class for objects containing EditEngine/Outliner text
  60
  61         This class implements the XAccessibleText interface for static
  62         text, somewhat similar to the children of the
  63         AccessibleTextHelper class. Currently, there are no children,
  64         i.e. the whole text is presented in one big chunk. This might
  65         change in the future, if a need for image bullets should
  66         arise. These, by convention, would be represented as children
  67         of the text.
  68
  69         You have to implement the SvxEditSource, SvxTextForwarder,
  70         SvxViewForwarder and SvxEditViewForwarder interfaces in order
  71         to enable your object to cooperate with this
  72         class. SvxTextForwarder encapsulates the fact that text
  73         objects do not necessarily have an EditEngine at their
  74         disposal, SvxViewForwarder and SvxEditViewForwarder do the
  75         same for the document and the edit view. The three mentioned
  76         forwarder objects are not stored by the AccessibleTextHelper,
  77         but fetched every time from the SvxEditSource. So you are best
  78         off making your SvxEditSource::Get*Forwarder methods cache the
  79         current forwarder.
  80
  81         As this class is intended for static (i.e. non-changing) text
  82         only, no event broadcasting is necessary. You must handle
  83         visibility by yourself, the bounding boxes returned by
  84         getCharacterBounds() are relative to your accessibility
  85         object.
  86
  87         @attention All public non-UNO methods (those are the uppercase
  88         ones) must not be called with any mutex hold, except when
  89         calling from the main thread (with holds the solar mutex),
  90         unless stated otherwise. This is because they themselves might
  91         need the solar mutex in addition to the object mutex, and the
  92         ordering of the locking must be: first solar mutex, then
  93         object mutex. Furthermore, state change events might be fired
  94         internally.
  95
  96         @derive Use this class as a base for objects containing static
  97         edit engine text. To avoid overwriting every interface method
  98         to intercept derived object defunc state, just set NULL as the
  99         edit source. Every interface method will then properly throw
 100         an exception.
 101     */
 102     class AccessibleStaticTextBase : public ::com::sun::star::accessibility::XAccessibleText
 103     {
 104
 105     public:
 106         /** Create accessible text object for given edit source
 107
 108             @param pEditSource
 109             The edit source to use. Object ownership is transferred
 110             from the caller to the callee. The object listens on the
 111             SvxEditSource for object disposal, so no provisions have
 112             to be taken if the caller destroys the data (e.g. the
 113             model) contained in the given SvxEditSource.
 114
 115         */
 116         explicit AccessibleStaticTextBase( ::std::auto_ptr< SvxEditSource > pEditSource );
 117         virtual ~AccessibleStaticTextBase();
 118
 119     private:
 120
 121         // declared, but not defined
 122         AccessibleStaticTextBase( const AccessibleStaticTextBase& );
 123         // declared, but not defined
 124         AccessibleStaticTextBase& operator= ( const AccessibleStaticTextBase& );
 125
 126     public:
 127         /** Query the current edit source
 128
 129             @attention This method returns by reference, so you are
 130             responsible for serialization (typically, you aquired the
 131             solar mutex when calling this method). Thus, the method
 132             should only be called from the main office thread.
 133
 134         */
 135         virtual const SvxEditSource& GetEditSource() const SAL_THROW((::com::sun::star::uno::RuntimeException));
 136
 137         /** Set the current edit source
 138
 139             @attention You are required to have the solar mutex
 140             locked, when calling this method. Thus, the method should
 141             only be called from the main office thread.
 142
 143             The EditSource set here is required to broadcast out the
 144             following hints: EDITSOURCE_HINT_PARASMOVED,
 145             EDITSOURCE_HINT_SELECTIONCHANGED, TEXT_HINT_MODIFIED,
 146             TEXT_HINT_PARAINSERTED, TEXT_HINT_PARAREMOVED,
 147             TEXT_HINT_TEXTHEIGHTCHANGED,
 148             TEXT_HINT_VIEWSCROLLED. Otherwise, not all state changes
 149             will get noticed by the accessibility object. Further
 150             more, when the corresponding core object or the model is
 151             dying, either the edit source must be set to NULL or it
 152             has to broadcast a SFX_HINT_DYING hint.
 153
 154             This class does not have a dispose method, since it is not
 155             a UNO component. Nevertheless, it holds C++ references to
 156             several core objects, so you should issue a
 157             SetEditSource(::std::auto_ptr<SvxEditSource>(NULL)) in
 158             your dispose() method.
 159
 160             @param pEditSource
 161             The new edit source to set. Object ownership is transferred
 162             from the caller to the callee.
 163         */
 164         virtual void SetEditSource( ::std::auto_ptr< SvxEditSource > pEditSource ) SAL_THROW((::com::sun::star::uno::RuntimeException));
 165
 166         /** Set the event source
 167
 168             @attention When setting a reference here, you should call
 169             Dispose() when you as the owner are disposing, since until
 170             then this object will hold that reference
 171
 172             @param rInterface
 173             The interface that should be set as the source for
 174             accessibility events sent by this object.
 175          */
 176         virtual void SetEventSource( const ::com::sun::star::uno::Reference< ::com::sun::star::accessibility::XAccessible >& rInterface );
 177
 178         /** Get the event source
 179
 180             @return the interface that is set as the source for
 181             accessibility events sent by this object.
 182          */
 183         virtual ::com::sun::star::uno::Reference< ::com::sun::star::accessibility::XAccessible > GetEventSource() const;
 184
 185         /** Set offset of EditEngine from parent
 186
 187             @attention You are required to have the solar mutex
 188             locked, when calling this method. Thus, the method should
 189             only be called from the main office thread.
 190
 191             If the origin of the underlying EditEngine does
 192             not correspond to the upper left corner of the object
 193             using this class, you have to specify the offset.
 194
 195             @param rPoint
 196             The offset in screen coordinates (i.e. pixel)
 197         */
 198         virtual void SetOffset( const Point& rPoint );
 199
 200         /** Query offset of EditEngine from parent
 201
 202             @return the offset in screen coordinates (i.e. pixel)
 203         */
 204         virtual Point GetOffset() const;
 205
 206         /** Update the visible children
 207
 208             As this class currently does not represent any content
 209             using children, this does nothing at the moment.
 210
 211             @attention You are required to have the solar mutex
 212             locked, when calling this method. Thus, the method should
 213             only be called from the main office thread.
 214
 215             This method reevaluates the visibility of all
 216             childrens. Call this method if your visibility state has
 217             changed somehow, e.g. if the visible area has changed and
 218             the AccessibleStaticTextHelper isn't notified
 219             internally. Normally, there should not be a need to call
 220             this method.
 221         */
 222         virtual void UpdateChildren() SAL_THROW((::com::sun::star::uno::RuntimeException));
 223
 224         /** Drop all references and enter disposed state
 225
 226             This method drops all references to external objects (also
 227             the event source reference set via SetEventSource()) and
 228             sets the object into the disposed state (i.e. the methods
 229             return default values or throw a uno::DisposedException
 230             exception).
 231          */
 232         virtual void Dispose();
 233
 234         // XAccessibleText interface implementation
 235         virtual sal_Int32 SAL_CALL getCaretPosition() throw (::com::sun::star::uno::RuntimeException);
 236         virtual sal_Bool SAL_CALL setCaretPosition( sal_Int32 nIndex ) throw (::com::sun::star::lang::IndexOutOfBoundsException, ::com::sun::star::uno::RuntimeException);
 237         virtual sal_Unicode SAL_CALL getCharacter( sal_Int32 nIndex ) throw (::com::sun::star::lang::IndexOutOfBoundsException, ::com::sun::star::uno::RuntimeException);
 238         virtual ::com::sun::star::uno::Sequence< ::com::sun::star::beans::PropertyValue > SAL_CALL getCharacterAttributes( sal_Int32 nIndex, const ::com::sun::star::uno::Sequence< ::rtl::OUString >& aRequestedAttributes ) throw (::com::sun::star::lang::IndexOutOfBoundsException, ::com::sun::star::uno::RuntimeException);
 239         virtual ::com::sun::star::awt::Rectangle SAL_CALL getCharacterBounds( sal_Int32 nIndex ) throw (::com::sun::star::lang::IndexOutOfBoundsException, ::com::sun::star::uno::RuntimeException);
 240         virtual sal_Int32 SAL_CALL getCharacterCount() throw (::com::sun::star::uno::RuntimeException);
 241         virtual sal_Int32 SAL_CALL getIndexAtPoint( const ::com::sun::star::awt::Point& aPoint ) throw (::com::sun::star::uno::RuntimeException);
 242         virtual ::rtl::OUString SAL_CALL getSelectedText() throw (::com::sun::star::uno::RuntimeException);
 243         virtual sal_Int32 SAL_CALL getSelectionStart() throw (::com::sun::star::uno::RuntimeException);
 244         virtual sal_Int32 SAL_CALL getSelectionEnd() throw (::com::sun::star::uno::RuntimeException);
 245         /// This will only work with a functional SvxEditViewForwarder, i.e. an EditEngine/Outliner in edit mode
 246         virtual sal_Bool SAL_CALL setSelection( sal_Int32 nStartIndex, sal_Int32 nEndIndex ) throw (::com::sun::star::lang::IndexOutOfBoundsException, ::com::sun::star::uno::RuntimeException);
 247         virtual ::rtl::OUString SAL_CALL getText() throw (::com::sun::star::uno::RuntimeException);
 248         virtual ::rtl::OUString SAL_CALL getTextRange( sal_Int32 nStartIndex, sal_Int32 nEndIndex ) throw (::com::sun::star::lang::IndexOutOfBoundsException, ::com::sun::star::uno::RuntimeException);
 249         /// Does not support AccessibleTextType::SENTENCE (missing feature in EditEngine)
 250         virtual ::com::sun::star::accessibility::TextSegment SAL_CALL getTextAtIndex( sal_Int32 nIndex, sal_Int16 aTextType ) throw (::com::sun::star::lang::IndexOutOfBoundsException, ::com::sun::star::lang::IllegalArgumentException, ::com::sun::star::uno::RuntimeException);
 251         /// Does not support AccessibleTextType::SENTENCE (missing feature in EditEngine)
 252         virtual ::com::sun::star::accessibility::TextSegment SAL_CALL getTextBeforeIndex( sal_Int32 nIndex, sal_Int16 aTextType ) throw (::com::sun::star::lang::IndexOutOfBoundsException, ::com::sun::star::lang::IllegalArgumentException, ::com::sun::star::uno::RuntimeException);
 253         /// Does not support AccessibleTextType::SENTENCE (missing feature in EditEngine)
 254         virtual ::com::sun::star::accessibility::TextSegment SAL_CALL getTextBehindIndex( sal_Int32 nIndex, sal_Int16 aTextType ) throw (::com::sun::star::lang::IndexOutOfBoundsException, ::com::sun::star::lang::IllegalArgumentException, ::com::sun::star::uno::RuntimeException);
 255         /// This will only work with a functional SvxEditViewForwarder, i.e. an EditEngine/Outliner in edit mode
 256         virtual sal_Bool SAL_CALL copyText( sal_Int32 nStartIndex, sal_Int32 nEndIndex ) throw (::com::sun::star::lang::IndexOutOfBoundsException, ::com::sun::star::uno::RuntimeException);
 257
 258         // child-related methods from XAccessibleContext
 259         virtual sal_Int32 SAL_CALL getAccessibleChildCount() throw (::com::sun::star::uno::RuntimeException);
 260         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);
 261
 262         // child-related methods from XAccessibleComponent
 263         virtual ::com::sun::star::uno::Reference< ::com::sun::star::accessibility::XAccessible > SAL_CALL getAccessibleAtPoint( const ::com::sun::star::awt::Point& aPoint ) throw (::com::sun::star::uno::RuntimeException);
 264
 265     private:
 266
 267         /// @dyn
 268         const std::auto_ptr< AccessibleStaticTextBase_Impl > mpImpl;
 269
 270     };
 271
 272 } // end of namespace accessibility
 273
 274 }//end of namespace binfilter
 275 #endif /* _SVX_ACCESSILE_STATIC_TEXT_BASE_HXX_ */