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 _SVX_ACCESSILE_STATIC_TEXT_BASE_HXX_
  21 #define _SVX_ACCESSILE_STATIC_TEXT_BASE_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         SAL_WNODEPRECATED_DECLARATIONS_PUSH
 105         explicit AccessibleStaticTextBase( ::std::auto_ptr< SvxEditSource > pEditSource );
 106         SAL_WNODEPRECATED_DECLARATIONS_POP
 107         virtual ~AccessibleStaticTextBase();
 108
 109     private:
 110
 111         // declared, but not defined
 112         EDITENG_DLLPRIVATE AccessibleStaticTextBase( const AccessibleStaticTextBase& );
 113         // declared, but not defined
 114         EDITENG_DLLPRIVATE AccessibleStaticTextBase& operator= ( const AccessibleStaticTextBase& );
 115
 116     public:
 117         /** Query the current edit source
 118
 119             @attention This method returns by reference, so you are
 120             responsible for serialization (typically, you aquired the
 121             solar mutex when calling this method). Thus, the method
 122             should only be called from the main office thread.
 123
 124         */
 125         virtual const SvxEditSource& GetEditSource() const SAL_THROW((::com::sun::star::uno::RuntimeException));
 126
 127         /** Set the current edit source
 128
 129             @attention You are required to have the solar mutex
 130             locked, when calling this method. Thus, the method should
 131             only be called from the main office thread.
 132
 133             The EditSource set here is required to broadcast out the
 134             following hints: EDITSOURCE_HINT_PARASMOVED,
 135             EDITSOURCE_HINT_SELECTIONCHANGED, TEXT_HINT_MODIFIED,
 136             TEXT_HINT_PARAINSERTED, TEXT_HINT_PARAREMOVED,
 137             TEXT_HINT_TEXTHEIGHTCHANGED,
 138             TEXT_HINT_VIEWSCROLLED. Otherwise, not all state changes
 139             will get noticed by the accessibility object. Further
 140             more, when the corresponding core object or the model is
 141             dying, either the edit source must be set to NULL or it
 142             has to broadcast a SFX_HINT_DYING hint.
 143
 144             This class does not have a dispose method, since it is not
 145             a UNO component. Nevertheless, it holds C++ references to
 146             several core objects, so you should issue a
 147             SetEditSource(::std::auto_ptr<SvxEditSource>(NULL)) in
 148             your dispose() method.
 149
 150             @param pEditSource
 151             The new edit source to set. Object ownership is transferred
 152             from the caller to the callee.
 153         */
 154         SAL_WNODEPRECATED_DECLARATIONS_PUSH
 155         virtual void SetEditSource( ::std::auto_ptr< SvxEditSource > pEditSource ) SAL_THROW((::com::sun::star::uno::RuntimeException));
 156         SAL_WNODEPRECATED_DECLARATIONS_POP
 157
 158         /** Set the event source
 159
 160             @attention When setting a reference here, you should call
 161             Dispose() when you as the owner are disposing, since until
 162             then this object will hold that reference
 163
 164             @param rInterface
 165             The interface that should be set as the source for
 166             accessibility events sent by this object.
 167          */
 168         virtual void SetEventSource( const ::com::sun::star::uno::Reference< ::com::sun::star::accessibility::XAccessible >& rInterface );
 169
 170         /** Get the event source
 171
 172             @return the interface that is set as the source for
 173             accessibility events sent by this object.
 174          */
 175         virtual ::com::sun::star::uno::Reference< ::com::sun::star::accessibility::XAccessible > GetEventSource() const;
 176
 177         /** Set offset of EditEngine from parent
 178
 179             @attention You are required to have the solar mutex
 180             locked, when calling this method. Thus, the method should
 181             only be called from the main office thread.
 182
 183             If the origin of the underlying EditEngine does
 184             not correspond to the upper left corner of the object
 185             using this class, you have to specify the offset.
 186
 187             @param rPoint
 188             The offset in screen coordinates (i.e. pixel)
 189         */
 190         virtual void SetOffset( const Point& rPoint );
 191
 192         /** Query offset of EditEngine from parent
 193
 194             @return the offset in screen coordinates (i.e. pixel)
 195         */
 196         virtual Point GetOffset() const;
 197
 198         /** Update the visible children
 199
 200             As this class currently does not represent any content
 201             using children, this does nothing at the moment.
 202
 203             @attention You are required to have the solar mutex
 204             locked, when calling this method. Thus, the method should
 205             only be called from the main office thread.
 206
 207             This method reevaluates the visibility of all
 208             children. Call this method if your visibility state has
 209             changed somehow, e.g. if the visible area has changed and
 210             the AccessibleStaticTextHelper isn't notified
 211             internally. Normally, there should not be a need to call
 212             this method.
 213         */
 214         virtual void UpdateChildren() SAL_THROW((::com::sun::star::uno::RuntimeException));
 215
 216         /** Drop all references and enter disposed state
 217
 218             This method drops all references to external objects (also
 219             the event source reference set via SetEventSource()) and
 220             sets the object into the disposed state (i.e. the methods
 221             return default values or throw a uno::DisposedException
 222             exception).
 223          */
 224         virtual void Dispose();
 225
 226         // XAccessibleText interface implementation
 227         virtual sal_Int32 SAL_CALL getCaretPosition() throw (::com::sun::star::uno::RuntimeException);
 228         virtual sal_Bool SAL_CALL setCaretPosition( sal_Int32 nIndex ) throw (::com::sun::star::lang::IndexOutOfBoundsException, ::com::sun::star::uno::RuntimeException);
 229         virtual sal_Unicode SAL_CALL getCharacter( sal_Int32 nIndex ) throw (::com::sun::star::lang::IndexOutOfBoundsException, ::com::sun::star::uno::RuntimeException);
 230         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);
 231         virtual ::com::sun::star::awt::Rectangle SAL_CALL getCharacterBounds( sal_Int32 nIndex ) throw (::com::sun::star::lang::IndexOutOfBoundsException, ::com::sun::star::uno::RuntimeException);
 232         virtual sal_Int32 SAL_CALL getCharacterCount() throw (::com::sun::star::uno::RuntimeException);
 233         virtual sal_Int32 SAL_CALL getIndexAtPoint( const ::com::sun::star::awt::Point& aPoint ) throw (::com::sun::star::uno::RuntimeException);
 234         virtual OUString SAL_CALL getSelectedText() throw (::com::sun::star::uno::RuntimeException);
 235         virtual sal_Int32 SAL_CALL getSelectionStart() throw (::com::sun::star::uno::RuntimeException);
 236         virtual sal_Int32 SAL_CALL getSelectionEnd() throw (::com::sun::star::uno::RuntimeException);
 237         /// This will only work with a functional SvxEditViewForwarder, i.e. an EditEngine/Outliner in edit mode
 238         virtual sal_Bool SAL_CALL setSelection( sal_Int32 nStartIndex, sal_Int32 nEndIndex ) throw (::com::sun::star::lang::IndexOutOfBoundsException, ::com::sun::star::uno::RuntimeException);
 239         virtual OUString SAL_CALL getText() throw (::com::sun::star::uno::RuntimeException);
 240         virtual OUString SAL_CALL getTextRange( sal_Int32 nStartIndex, sal_Int32 nEndIndex ) throw (::com::sun::star::lang::IndexOutOfBoundsException, ::com::sun::star::uno::RuntimeException);
 241         /// Does not support AccessibleTextType::SENTENCE (missing feature in EditEngine)
 242         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);
 243         /// Does not support AccessibleTextType::SENTENCE (missing feature in EditEngine)
 244         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);
 245         /// Does not support AccessibleTextType::SENTENCE (missing feature in EditEngine)
 246         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);
 247         /// This will only work with a functional SvxEditViewForwarder, i.e. an EditEngine/Outliner in edit mode
 248         virtual sal_Bool SAL_CALL copyText( sal_Int32 nStartIndex, sal_Int32 nEndIndex ) throw (::com::sun::star::lang::IndexOutOfBoundsException, ::com::sun::star::uno::RuntimeException);
 249
 250         // XAccessibleTextAttributes
 251         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);
 252         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);
 253
 254         // child-related methods from XAccessibleContext
 255         virtual sal_Int32 SAL_CALL getAccessibleChildCount() throw (::com::sun::star::uno::RuntimeException);
 256         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);
 257
 258         // child-related methods from XAccessibleComponent
 259         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);
 260
 261     protected:
 262         Rectangle GetParagraphBoundingBox() const;
 263
 264     private:
 265
 266         /// @dyn
 267         SAL_WNODEPRECATED_DECLARATIONS_PUSH
 268         const std::auto_ptr< AccessibleStaticTextBase_Impl > mpImpl;
 269         SAL_WNODEPRECATED_DECLARATIONS_POP
 270
 271     };
 272
 273 } // end of namespace accessibility
 274
 275 #endif /* _SVX_ACCESSILE_STATIC_TEXT_BASE_HXX_ */
 276
 277 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */