include/svx/AccessibleTextHelper.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_TEXT_HELPER_HXX_
  21 #define _SVX_ACCESSILE_TEXT_HELPER_HXX_
  22
  23 #include <memory>
  24 #include <sal/types.h>
  25 #include <tools/gen.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/XAccessibleContext.hpp>
  30 #include <com/sun/star/accessibility/XAccessibleComponent.hpp>
  31 #include <com/sun/star/accessibility/XAccessibleEventBroadcaster.hpp>
  32 #include "svx/svxdllapi.h"
  33
  34
  35 class SvxTextForwarder;
  36 class SvxViewForwarder;
  37 class SvxEditSource;
  38
  39 namespace accessibility
  40 {
  41
  42     class AccessibleTextHelper_Impl;
  43
  44     /** Helper class for objects containing EditEngine/Outliner text
  45
  46         This class provides the methods from the XAccessibleContext,
  47         XAccessibleEventBroadcaster and XAccessibleComponent
  48         interfaces, that are common to all accessible objects
  49         containing an edit engine.
  50
  51         The text contained in the EditEngine/Outliner is presented as
  52         children of this class, namely for every text paragraph a
  53         AccessibleEditableTextPara child object is generated. As this
  54         class manages these children for itself, it has to send out
  55         AccessibleEventId::CHILD events on your
  56         behalf. Thus, you must forward every call to your
  57         addEventListener()/removeEventListener() methods to the
  58         AccessibleTextHelper (methods
  59         AddEventListener/RemoveEventListener), otherwise none or not
  60         every one of your event listener will notice child changes.
  61
  62         You have to implement the SvxEditSource, SvxTextForwarder,
  63         SvxViewForwarder and SvxEditViewForwarder interfaces in order
  64         to enable your object to cooperate with this
  65         class. SvxTextForwarder encapsulates the fact that text
  66         objects do not necessarily have an EditEngine at their
  67         disposal, SvxViewForwarder and SvxEditViewForwarder do the
  68         same for the document and the edit view. The three mentioned
  69         forwarder objects are not stored by the AccessibleTextHelper,
  70         but fetched every time from the SvxEditSource. So you are best
  71         off making your SvxEditSource::Get*Forwarder methods cache the
  72         current forwarder.
  73
  74         To support changes in edit mode or conversion of fixed text
  75         into EditEngine text, you can change the SvxEditSource this
  76         class is referring to. This might render all children invalid
  77         and change the child count, since the AccessibleTextHelper
  78         reinitializes itself from scratch.
  79
  80         This class registers itself at the SvxEditSource as a state
  81         listener and manages the state of its children (i.e. the
  82         paragraphs). See the method documentation of
  83         AccessibleTextHelper::SetEditSource for the expected
  84         events. Generally, be prepared that when sending any of these
  85         events via SvxEditSource::GetBroadcaster() broadcaster, the
  86         AccessibleTextHelper will call the SvxEditSource and their
  87         forwarder to update it's state. Avoid being inconsistent in
  88         the facts you tell in the events, e.g. when sending a
  89         TEXT_HINT_PARAINSERTED event, the
  90         SvxEditSource::GetTextForwarder().GetParagraphCount() should
  91         already include the newly inserted paragraph.
  92
  93         @attention All public methods must not be called with any
  94         mutex hold, except when calling from the main thread (with
  95         holds the solar mutex), unless stated otherwise. This is
  96         because they themselves might need the solar mutex in addition
  97         to the object mutex, and the ordering of the locking must be:
  98         first solar mutex, then object mutex. Furthermore, state
  99         change events might be fired internally.
 100
 101         @derive Use this class in an aggregation and forward, or
 102         derive from it and overwrite. If the Remove/AddEventListener
 103         methods are overwritten, make sure FireEvent is adapted,
 104         too.
 105
 106         @see SvxEditSource
 107         @see SvxTextForwarder
 108         @see SvxViewForwarder
 109         @see SvxEditViewForwarder
 110     */
 111     class SVX_DLLPUBLIC AccessibleTextHelper
 112     {
 113
 114     public:
 115         typedef ::std::vector< sal_Int16 > VectorOfStates;
 116
 117         /** Create accessible text object for given edit source
 118
 119             @param pEditSource
 120             The edit source to use. Object ownership is transferred
 121             from the caller to the callee. The object listens on the
 122             SvxEditSource for object disposal, so no provisions have
 123             to be taken if the caller destroys the data (e.g. the
 124             model) contained in the given SvxEditSource.
 125
 126         */
 127         SAL_WNODEPRECATED_DECLARATIONS_PUSH
 128         explicit AccessibleTextHelper( ::std::auto_ptr< SvxEditSource > pEditSource );
 129         SAL_WNODEPRECATED_DECLARATIONS_POP
 130         virtual ~AccessibleTextHelper();
 131
 132     protected:
 133
 134         // declared, but not defined
 135         AccessibleTextHelper( const AccessibleTextHelper& );
 136         // declared, but not defined
 137         AccessibleTextHelper& operator= ( const AccessibleTextHelper& );
 138
 139     public:
 140         /** Query the current edit source
 141
 142             @attention This method returns by reference, so you are
 143             responsible for serialization (typically, you aquired the
 144             solar mutex when calling this method). Thus, the method
 145             should only be called from the main office thread.
 146
 147          */
 148         virtual const SvxEditSource& GetEditSource() const SAL_THROW((::com::sun::star::uno::RuntimeException));
 149
 150         /** Set the current edit source
 151
 152             @attention Might fire state change events, therefore,
 153             don't hold any mutex except solar mutex, which you are
 154             required to lock before. This method should only be called
 155             from the main office thread.
 156
 157             The EditSource set here is required to broadcast out the
 158             following hints: EDITSOURCE_HINT_PARASMOVED,
 159             EDITSOURCE_HINT_SELECTIONCHANGED, TEXT_HINT_MODIFIED,
 160             TEXT_HINT_PARAINSERTED, TEXT_HINT_PARAREMOVED,
 161             TEXT_HINT_TEXTHEIGHTCHANGED,
 162             TEXT_HINT_VIEWSCROLLED. Otherwise, not all state changes
 163             will get noticed by the accessibility object. Further
 164             more, when the corresponding core object or the model is
 165             dying, either the edit source must be set to NULL or it
 166             has to broadcast a SFX_HINT_DYING hint.
 167
 168             If the SvxEditSource's managed text can change between
 169             edit/non-edit mode (i.e. there are times when
 170             SvxEditSource::GetEditViewForwarder(sal_False) returns
 171             NULL), then the two additional hints are required:
 172             HINT_BEGEDIT and HINT_ENDEDIT. When the
 173             AccessibleTextHelper receives a HINT_BEGEDIT, it expects
 174             the SvxEditSource already in edit mode. On a HINT_ENDEDIT,
 175             edit mode must already been left. The rationale for these
 176             events are the fact that focus and selection have to be
 177             updated in edit mode, and completely relinquished and
 178             reset to the parent (for the focus) in non-edit mode.
 179
 180             This class does not have a dispose method, since it is not
 181             a UNO component. Nevertheless, it holds C++ references to
 182             several core objects, so you should issue a
 183             SetEditSource(::std::auto_ptr<SvxEditSource>(NULL)) in
 184             your dispose() method.
 185
 186             @param pEditSource
 187             The new edit source to set. Object ownership is transferred
 188             from the caller to the callee.
 189         */
 190         SAL_WNODEPRECATED_DECLARATIONS_PUSH
 191         virtual void SetEditSource( ::std::auto_ptr< SvxEditSource > pEditSource ) SAL_THROW((::com::sun::star::uno::RuntimeException));
 192         SAL_WNODEPRECATED_DECLARATIONS_POP
 193
 194         /** Set the event source
 195
 196             You should set the event source before registering any
 197             event listener and before requesting any child. Children
 198             of this object receive the event source as their parent
 199             accessible object. That is, the event source is best set
 200             in your object's init method.
 201
 202             @attention When setting a reference here, you should call
 203             Dispose() when you as the owner are disposing, since until
 204             then this object will hold that reference
 205
 206             @param rInterface
 207             The interface that should be set as the source for
 208             accessibility events sent by this object.
 209          */
 210         virtual void SetEventSource( const ::com::sun::star::uno::Reference< ::com::sun::star::accessibility::XAccessible >& rInterface );
 211
 212         /** Get the event source
 213
 214             @return the interface that is set as the source for
 215             accessibility events sent by this object.
 216          */
 217         virtual ::com::sun::star::uno::Reference< ::com::sun::star::accessibility::XAccessible > GetEventSource() const;
 218
 219         /** Set offset of EditEngine/Outliner from parent
 220
 221             If the origin of the underlying EditEngine/Outliner does
 222             not correspond to the upper left corner of the object
 223             using this class, you have to specify the offset.
 224
 225             @attention Might fire state change events, therefore,
 226             don't hold any mutex except solar mutex, which you are
 227             required to lock before. This method should only be called
 228             from the main office thread.
 229
 230             @param rPoint
 231             The offset in screen coordinates (i.e. pixel)
 232         */
 233         virtual void SetOffset( const Point& rPoint );
 234
 235         /** Query offset of EditEngine/Outliner from parent
 236
 237             @return the offset in screen coordinates (i.e. pixel)
 238         */
 239         virtual Point GetOffset() const;
 240
 241         /** Set offset the object adds to all children's indices
 242
 243             This can be used if the owner of this object has children
 244             handled by itself. Setting an offset different from 0
 245             leads to this object mimicking that all it's children are
 246             within the range [nOffset, GetChildCount()+nOffset). That
 247             means, GetChild() also expects the index to be in this
 248             range.
 249
 250             @attention Might fire state change events, therefore,
 251             don't hold any mutex except solar mutex, which you are
 252             required to lock before. This method should only be called
 253             from the main office thread.
 254
 255             @param nOffset
 256             The offset to add to every children's index.
 257         */
 258         virtual void SetStartIndex( sal_Int32 nOffset );
 259
 260         /** Query offset the object adds to all children's indices
 261
 262             @return the offset to add to every children's index.
 263         */
 264         virtual sal_Int32 GetStartIndex() const;
 265
 266         /** Sets a vector of additional accessible states.
 267
 268             The states are passed to every created child object
 269             (text paragraph). The state values are defined in
 270             com::sun::star::accessibility::AccessibleStateType.
 271
 272             This function has to be called before querying for
 273             any children (e.g. with GetChild()).
 274          */
 275         void SetAdditionalChildStates( const VectorOfStates& rChildStates );
 276
 277         /** Update the visible children
 278
 279             @attention Might fire state change events, therefore,
 280             don't hold any mutex except solar mutex, which you are
 281             required to lock before. This method should only be called
 282             from the main office thread.
 283
 284             This method reevaluates the visibility of all
 285             children. Call this method if your visibility state has
 286             changed somehow, e.g. if the visible area has changed and
 287             the AccessibleTextHelper isn't notified internally
 288             (e.g. via TEXT_HINT_VIEWSCROLLED). Normally, there should
 289             not be a need to call this method.
 290         */
 291         virtual void UpdateChildren() SAL_THROW((::com::sun::star::uno::RuntimeException));
 292
 293         /** Drop all references and enter disposed state
 294
 295             This method drops all references to external objects (also
 296             the event source reference set via SetEventSource()) and
 297             sets the object into the disposed state (i.e. the methods
 298             return default values or throw a uno::DisposedException
 299             exception).
 300          */
 301         virtual void Dispose();
 302
 303         /** Set the focus state of the accessibility object
 304
 305             Since this class handles children which also might get the
 306             focus, the user of this class is encouraged to delegate
 307             focus handling. Whenever the focus state of the
 308             surrounding object changes, this method has to be called.
 309
 310             The protocol of focus handling for a user of this class is
 311             then to call SetFocus() with the appropriate focus state,
 312             and HaveFocus() to determine the focus state you tell the
 313             outside.
 314
 315             @attention Might fire state change events, therefore,
 316             don't hold any mutex except solar mutex, which you are
 317             required to lock before. This method should only be called
 318             from the main office thread.
 319
 320             @param bHaveFocus
 321             Whether we got or we lost the focus. Set to sal_True if
 322             focus is gotten, sal_False otherwise.
 323
 324             @see HaveFocus()
 325          */
 326         virtual void SetFocus( sal_Bool bHaveFocus = sal_True ) SAL_THROW((::com::sun::star::uno::RuntimeException));
 327
 328         /** Query the focus state of the surrounding object
 329
 330             If focus handling is delegated to this class, determine
 331             focus state with this method. Be prepared that even if you
 332             set the focus with SetFocus(sal_True), this method might
 333             return sal_False. This is the case if one of the children
 334             actually got the focus.
 335
 336             @return the state of the focus ownership
 337          */
 338         virtual sal_Bool HaveFocus() SAL_THROW((::com::sun::star::uno::RuntimeException));
 339
 340         /** Call this method to invoke all event listeners with the given event
 341
 342             @attention Fires state change events, therefore, don't hold any mutex
 343
 344             @param nEventId
 345             Id of the event to send, @see AccessibleEventId
 346
 347             @param rNewValue
 348             The value we've changed into
 349
 350             @param rOldValue
 351             The old value before the change
 352         */
 353         virtual void FireEvent( const sal_Int16 nEventId,
 354                                 const ::com::sun::star::uno::Any& rNewValue = ::com::sun::star::uno::Any(),
 355                                 const ::com::sun::star::uno::Any& rOldValue = ::com::sun::star::uno::Any() ) const;
 356
 357         /** Call this method to invoke all event listeners with the given event
 358
 359             @attention Fires state change events, therefore, don't hold any mutex
 360
 361             @param rEvent
 362             The event to send, @see AccessibleEventObject
 363
 364         */
 365         // TODO: make that virtual next time
 366         void FireEvent( const ::com::sun::star::accessibility::AccessibleEventObject& rEvent ) const;
 367
 368         /** Query select state of the text managed by this object
 369
 370             @attention Don't call with locked mutexes. You may hold
 371             the solar mutex, but this method aquires it anyway.
 372
 373             @return sal_True, if the text or parts of it are currently selected
 374         */
 375         virtual sal_Bool IsSelected() const;
 376
 377         // XAccessibleContext child handling methods
 378         //-----------------------------------------------------------------
 379         /** Implements getAccessibleChildCount
 380
 381             @attention Don't call with locked mutexes. You may hold
 382             the solar mutex, but this method aquires it anyway.
 383         */
 384         virtual sal_Int32 GetChildCount() SAL_THROW((::com::sun::star::uno::RuntimeException));
 385         /** Implements getAccessibleChild
 386
 387             @attention Don't call with locked mutexes. You may hold
 388             the solar mutex, but this method aquires it anyway.
 389         */
 390         virtual ::com::sun::star::uno::Reference< ::com::sun::star::accessibility::XAccessible > GetChild( sal_Int32 i ) SAL_THROW((::com::sun::star::lang::IndexOutOfBoundsException, ::com::sun::star::uno::RuntimeException));
 391
 392         // XAccessibleEventBroadcaster child related methods
 393         //-----------------------------------------------------------------
 394         /** Implements addEventListener
 395
 396             @attention Don't call with locked mutexes
 397         */
 398         virtual void AddEventListener( const ::com::sun::star::uno::Reference< ::com::sun::star::accessibility::XAccessibleEventListener >& xListener ) SAL_THROW((::com::sun::star::uno::RuntimeException));
 399         /** Implements removeEventListener
 400
 401             @attention Don't call with locked mutexes
 402         */
 403         virtual void RemoveEventListener( const ::com::sun::star::uno::Reference< ::com::sun::star::accessibility::XAccessibleEventListener >& xListener ) SAL_THROW((::com::sun::star::uno::RuntimeException));
 404
 405         // XAccessibleComponent child related methods
 406         //-----------------------------------------------------------------
 407         /** Implements getAccessibleAt
 408
 409             @attention Don't call with locked mutexes. You may hold
 410             the solar mutex, but this method aquires it anyway.
 411         */
 412         virtual ::com::sun::star::uno::Reference< ::com::sun::star::accessibility::XAccessible > SAL_CALL GetAt( const ::com::sun::star::awt::Point& aPoint ) SAL_THROW((::com::sun::star::uno::RuntimeException));
 413
 414     private:
 415
 416         /// @dyn
 417         const std::auto_ptr< AccessibleTextHelper_Impl > mpImpl;
 418
 419     };
 420
 421 } // end of namespace accessibility
 422
 423 #endif /* _SVX_ACCESSILE_TEXT_HELPER_HXX_ */
 424
 425 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */