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